Stay organized with collections
Save and categorize content based on your preferences.
Create a metadata bucket
This guide describes how to create a metadata bucket. You can create a metadata
bucket using the Configuration API or Manufacturing Data Engine (MDE) web interface.
Before you begin
Before you begin creating a bucket, read
how to model metadata
section in the MDE documentation.
Buckets naming
When you create a bucket, the name must be unique in a
MDE deployment. Bucket names must not
contain spaces or special characters such
as &, @, or %.
Create a metadata bucket
You can create a metadata bucket using either the terminal or the console
interface.
BUCKET_NAME: The name of the bucket to be created.
BUCKET_TYPE: The type of the bucket to be created. Must be one of
TAG, RECORD, or LOOKUP. The natural_key of a metadata instance
in a TAG bucket must be a tag name. The natural_key of a metadata
instance in a RECORD bucket can be any key. The natural_key of a
metadata instance in a LOOKUP bucket can be any key, but records can't
reference instances in a lookup bucket, and the instances are not
written to any data sink. Lookup buckets only serve as source of
reference data that can be retrieved by the parser using the
Whistle function lookupByKey and used to enrich records.
BUCKET_SCHEMA: The JSON schema of the bucket. The schema constrains
the instances that may be created in the bucket.
INSTANCE_OVERWRITE_MODE: Either TRUE or FALSE. Determines whether
new instances are created by merging the provided instance with the
latest instance for a given natural key or if new instances are created
as provided.
Console
To add new metadata bucket using the console click the METADATA
section of the top menu of Cloud Management section. The Metadata
configuration page lists the available Buckets in the
MDE instance:
For each Bucket the following information is provided:
Name: The name of the bucket. Each name needs to be unique.
Version: The Version of the bucket. Only the latest available
version is displayed by default. To display earlier versions un-check
the 'Only Latest' check-box.
Bucket type: It visualizes the type of bucket. Three different bucket
types are supported:
Tag: Buckets that qualify a given tag. They are associated to a
type and inherited by all tags of that given type. They
can be instantiated at tag level as they intend to qualify the
variable itself and not any of its specific records. An example of a
tag Bucket could be the 'Asset hierarchy' or the 'Units of Measure'
of the tag.
Record: Record buckets qualify each of the Records of a
given tag. They are also associated to a type and inherited
by the tag but are instantiated at the Record level. Each
Record is expected to have a different value among a limited set
of Bucket Instances. An example of Record Bucket could be
the 'Shift' or the 'Operator Name'.
Reference: Buckets that define a set of
key value pairs between a user-defined Key and an instance.
To create a new Bucket click Add new metadata bucket:
Fill out the form displayed from the side panel with the necessary Bucket
parameters:
Bucket Name: A unique, user defined name for the bucket.
Bucket type: To define the Bucket class.
Instance update mode: It specifies the type of instance updates
specified for the metadata bucket:
Instance Override: The existing instance is replaced by the
latest instance received from the edge, even if it's incomplete.
Instance Merge: The existing instance is merged with the latest
instance received from the edge. Only the attributed contained in
the new edge instance are replaced.
JSON Schema: The JSON Schema defining the structure of the
bucket. Need to be a valid Schema. All metadata instances are
validated against the bucket schema.
The following is a sample JSON Schema of a default metadata bucket
provided by the default configuration package:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Create a metadata bucket\n========================\n\nThis guide describes how to create a metadata bucket. You can create a metadata\nbucket using the Configuration API or Manufacturing Data Engine (MDE) web interface.\n\nBefore you begin\n----------------\n\nBefore you begin creating a bucket, read\n[how to model metadata](/manufacturing-data-engine/docs/guides/model/how-to-model-data#metadata_modeling)\nsection in the MDE documentation.\n\nBuckets naming\n--------------\n\nWhen you create a bucket, the name must be unique in a\nMDE deployment. Bucket names must not\ncontain spaces or special characters such\nas `&`, `@`, or `%`.\n\nCreate a metadata bucket\n------------------------\n\nYou can create a metadata bucket using either the terminal or the console\ninterface. \n\n### REST\n\n\nExecute the following REST API request:\n\n`POST /metadata/v1/buckets` \n\n {\n \"name\": \"\u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e\",\n \"type\": \"\u003cvar translate=\"no\"\u003eBUCKET_TYPE\u003c/var\u003e\",\n \"schema\": \"\u003cvar translate=\"no\"\u003eBUCKET_SCHEMA\u003c/var\u003e\",\n \"provider\": \"local\",\n \"attributes\": {\n \"instanceOverwriteMode\": \"\u003cvar translate=\"no\"\u003eINSTANCE_OVERWRITE_MODE\u003c/var\u003e\"\n }\n }\n\nReplace the following:\n\n- `BUCKET_NAME`: The name of the bucket to be created.\n- `BUCKET_TYPE`: The type of the bucket to be created. Must be one of `TAG`, `RECORD`, or `LOOKUP`. The `natural_key` of a metadata instance in a `TAG` bucket must be a tag name. The `natural_key` of a metadata instance in a `RECORD` bucket can be any key. The `natural_key` of a metadata instance in a `LOOKUP` bucket can be any key, but records can't reference instances in a lookup bucket, and the instances are not written to any data sink. Lookup buckets only serve as source of reference data that can be retrieved by the parser using the Whistle function `lookupByKey` and used to enrich records.\n- `BUCKET_SCHEMA`: The JSON schema of the bucket. The schema constrains the instances that may be created in the bucket.\n- `INSTANCE_OVERWRITE_MODE`: Either `TRUE` or `FALSE`. Determines whether new instances are created by merging the provided instance with the latest instance for a given natural key or if new instances are created as provided.\n\n### Console\n\nTo add new **metadata bucket** using the console click the **METADATA**\nsection of the top menu of **Cloud Management** section. The **Metadata**\nconfiguration page lists the available **Buckets** in the\nMDE instance:\n\nFor each **Bucket** the following information is provided:\n\n- **Name**: The name of the bucket. Each name needs to be unique.\n- **Version**: The Version of the bucket. Only the latest available version is displayed by default. To display earlier versions un-check the 'Only Latest' check-box.\n- **Bucket type** : It visualizes the type of bucket. Three different bucket types are supported:\n 1. **Tag**: Buckets that qualify a given tag. They are associated to a type and inherited by all tags of that given type. They can be instantiated at tag level as they intend to qualify the variable itself and not any of its specific records. An example of a tag Bucket could be the 'Asset hierarchy' or the 'Units of Measure' of the tag.\n 2. **Record**: Record buckets qualify each of the Records of a given tag. They are also associated to a type and inherited by the tag but are instantiated at the Record level. Each Record is expected to have a different value among a limited set of Bucket Instances. An example of Record Bucket could be the 'Shift' or the 'Operator Name'.\n 3. **Reference**: Buckets that define a set of key value pairs between a user-defined Key and an instance.\n\nTo create a new **Bucket** click **Add new metadata bucket**:\n\nFill out the form displayed from the side panel with the necessary Bucket\nparameters:\n\n- **Bucket Name**: A unique, user defined name for the bucket.\n- **Bucket type**: To define the Bucket class.\n- **Instance update mode** : It specifies the type of instance updates specified for the metadata bucket:\n 1. **Instance Override**: The existing instance is replaced by the latest instance received from the edge, even if it's incomplete.\n 2. **Instance Merge**: The existing instance is merged with the latest instance received from the edge. Only the attributed contained in the new edge instance are replaced.\n- **JSON Schema** : The `JSON Schema` defining the structure of the bucket. Need to be a valid Schema. All metadata instances are validated against the bucket schema.\n\nThe following is a sample `JSON Schema` of a default metadata bucket\nprovided by the default configuration package: \n\n {\n \"$id\": \"https://gmde.cloud/tag.schema.json\",\n \"$schema\": \"https://json-schema.org/draft/2019-09/schema\",\n \"title\": \"Tag metadata bucket\",\n \"type\": \"object\",\n \"properties\": {\n \"datatype\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"registerId\": {\n \"type\": \"string\"\n },\n \"edgeTagName\": {\n \"type\": \"string\"\n },\n \"tagName\": {\n \"description\": \"Tag name\",\n \"type\": \"string\"\n },\n \"deviceID\": {\n \"type\": \"string\"\n },\n \"deviceName\": {\n \"type\": \"string\"\n },\n \"deviceMetadata\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\"tagName\"],\n \"additionalProperties\": false\n }"]]