Stay organized with collections
Save and categorize content based on your preferences.
Create a metadata bucket version
This guide describes how to create a new metadata bucket version for an existing
bucket in Manufacturing Data Engine (MDE).
Metadata bucket versions lets you evolve the bucket schema. Types and parsers
always reference a specific bucket version, so when you create a new version,
it doesn't affect the existing data processing pipelines. You must upgrade your
types and parsers or create new types and parsers to use the new bucket version.
You can create a metadata bucket version using the configuration API or
MDE web interface.
Before you begin
This guide requires you have already created a
metadata bucket
for the MDE.
Versioning restrictions
When creating new versions of a bucket, consider the following limitations:
New versions may:
Add new optional fields.
Mark a required field optional.
New versions may not:
Remove fields.
Change data type of existing fields.
Mark an an optional attribute required.
Create a new metadata bucket version
You can create a metadata bucket version using the terminal or the console.
REST
Execute the following REST API request:
POST /metadata/v1/buckets/BUCKET_NAME/versions
{"schema":"BUCKET_SCHEMA","provider":"local"}
Replace the following:
BUCKET_NAME: Name of the bucket to be created.
BUCKET_TYPE: 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 a parser using the
Whistle function lookupByKey and used to enrich records.
BUCKET_SCHEMA: 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 create a new metadata bucket version click
Create New Version from the METADATA section of the
Cloud Management MC web interface:
A configuration panel is displayed with a form to update the parameters of
the new metadata bucket version:
Only backward compatible changes are allowed for
new versions. New, breaking, and changes requires creating a new bucket.
In the panel you can update the following:
Instance update mode: Change the instance ingestion behavior of
the bucket.
Metadata schema: Add new attributes to the existing schema of the
bucket.
After the changes are implemented, click CREATE to save the
new version of the metadata bucket.
An error message is displayed if the
change is unsuccessful. A success message is shown if the change is
successful. The new version number is sequential and is
automatically assigned to the bucket.
[[["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 version\n================================\n\nThis guide describes how to create a new metadata bucket version for an existing\nbucket in Manufacturing Data Engine (MDE).\n\nMetadata bucket versions lets you evolve the bucket schema. Types and parsers\nalways reference a specific bucket version, so when you create a new version,\nit doesn't affect the existing data processing pipelines. You must upgrade your\ntypes and parsers or create new types and parsers to use the new bucket version.\nYou can create a metadata bucket version using the configuration API or\nMDE web interface.\n\nBefore you begin\n----------------\n\nThis guide requires you have already created a\n[metadata bucket](/manufacturing-data-engine/docs/guides/model/how-to-create-a-metadata-bucket)\nfor the MDE.\n\nVersioning restrictions\n-----------------------\n\nWhen creating new versions of a bucket, consider the following limitations:\n\n**New versions may:**\n\n- Add new optional fields.\n- Mark a required field optional.\n\n**New versions may not:**\n\n- Remove fields.\n- Change data type of existing fields.\n- Mark an an optional attribute required.\n\nCreate a new metadata bucket version\n------------------------------------\n\nYou can create a metadata bucket version using the terminal or the console. \n\n### REST\n\n\nExecute the following REST API request:\n\n`POST /metadata/v1/buckets/`\u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e`/versions` \n\n {\n \"schema\": \"\u003cvar translate=\"no\"\u003eBUCKET_SCHEMA\u003c/var\u003e\",\n \"provider\": \"local\"\n }\n\nReplace the following:\n\n- `BUCKET_NAME`: Name of the bucket to be created.\n- `BUCKET_TYPE`: 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 a parser using the Whistle function `lookupByKey` and used to enrich records.\n- `BUCKET_SCHEMA`: 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\n1. To create a **new metadata bucket version** click\n **Create New Version** from the **METADATA** section of the\n **Cloud Management MC** web interface:\n\n2. A configuration panel is displayed with a form to update the parameters of\n the new **metadata bucket version**:\n\n Only **backward compatible** changes are allowed for\n new versions. New, breaking, and changes requires creating a new bucket.\n In the panel you can update the following:\n - **Instance update mode**: Change the instance ingestion behavior of the bucket.\n - **Metadata schema**: Add new attributes to the existing schema of the bucket.\n3. After the changes are implemented, click **CREATE** to save the\n new version of the metadata bucket.\n\n4. An error message is displayed if the\n change is unsuccessful. A success message is shown if the change is\n successful. The new version number is sequential and is\n automatically assigned to the bucket."]]
