Tags allow users to organize and categorize database objects such as tables, views, and schemas. Tags act as metadata labels for database assets, enabling easier management, organization, and control of data within your platform. Tagging is supported in Snowflake, Databricks, and BigQuery projects.

BigQuery calls this feature labels rather than tags. The concept and the SqlDBM experience are the same, so throughout this article read "tag" as "label" when working in a BigQuery project. Where platform behavior genuinely differs, it is called out explicitly.

In SqlDBM, users can manage their Tags like any other database object and assign them using the diagrams and through object properties. A tag instance is a reusable, project-level object; a tag assignment is the relationship between that instance and a database object. Create a tag once and assign it to as many objects as you need.

Reverse Engineer Tags

Tags can be added to a project through standard Reverse Engineering. Please ensure that your role has the required permissions to reference Tag DDL.

On any import path, if a matching tag instance does not exist in the project it is created and assigned. If it already exists, only the assignment is created. The available import paths differ by platform:

BigQuery

Labels are read from live connections and from DDL imports, where they appear in the object's OPTIONS (labels = [...]) clause. Uppercase keys or values encountered during import are converted to lowercase before the label instance or assignment is created, rather than being rejected.

Databricks

Databricks tags do not appear in an object's CREATE statement or in SHOW CREATE TABLE output, so they are imported from the ALTER statements in a DDL script. SqlDBM recognizes SET TAGS and UNSET TAGS on ALTER SCHEMA, ALTER TABLE, ALTER VIEW, ALTER MATERIALIZED VIEW, and ALTER TABLE ... ALTER COLUMN - one column per statement.

Multiple SET TAGS statements for the same object are applied cumulatively, and a later UNSET TAGS removes the assignment. Tag statements are never silently ignored: each one is either applied to the model or raises an entry in Errors & Warnings.

Importing Databricks tags with Direct Connect

Direct Connect does not read tag assignments from Unity Catalog directly. Instead, import your objects with Direct Connect as usual, then upload an Excel file containing the tag assignments.

Run the following query in Databricks and export the result to Excel. Set the catalog and schema variables to the catalog and schema you are importing.

DECLARE OR REPLACE VARIABLE catalog STRING DEFAULT 'myCatalog';
DECLARE OR REPLACE VARIABLE schema STRING DEFAULT 'mySchema';

SELECT
  'SCHEMA' AS entity_type,
  catalog_name,
  schema_name,
  NULL AS table_name,
  NULL AS column_name,
  tag_name,
  tag_value
FROM system.information_schema.schema_tags
WHERE catalog_name = catalog    -- No colon! References the variable directly
  AND schema_name = schema      -- No colon!

UNION ALL

SELECT
  'TABLE',
  catalog_name,
  schema_name,
  table_name,
  NULL,
  tag_name,
  tag_value
FROM system.information_schema.table_tags
WHERE catalog_name = catalog
  AND schema_name = schema

UNION ALL

SELECT
  'COLUMN',
  catalog_name,
  schema_name,
  table_name,
  column_name,
  tag_name,
  tag_value
FROM system.information_schema.column_tags
WHERE catalog_name = catalog
  AND schema_name = schema

ORDER BY entity_type, table_name, column_name, tag_name

The uploaded file must use the following header columns, in this order: entity_type, catalog_name, schema_name, table_name, column_name, tag_name, tag_value.

• entity_type is SCHEMA, TABLE, or COLUMN. table_name is empty for schema tags, and column_name is empty for schema and object tags.

• tag_name is required. Leave tag_value empty for a key-only tag.

• Tags are only assigned to database objects that match the uploaded row. The Discard database name setting is honored when matching.

• Rows whose target does not match an object in the project are skipped, and each skipped row raises a warning containing the tag name, entity type, and the target's fully qualified name.

<<img>> Databricks Reverse Engineer screen showing the tag Excel upload step

Tags in RE XLSX files

Both the structure XLSX and the dictionary (database documentation) XLSX handle tags identically.

• Tags tab (Labels tab in BigQuery) - defines tag instances with no assignment. Columns: TAG KEY and TAG VALUE, or LABEL NAME and LABEL VALUE in BigQuery.

• Objects tab - a TAGS (LABELS) column defines object-level assignments as comma-separated key : value pairs, for example env : prod, team : data-engineering, domain : ecommerce.

• Columns tab - a TAGS column in the same format, for Snowflake and Databricks column tags. Not applicable to BigQuery.

In the RE import summary, tags are reported at the object level only - for example, "table orders: 2 tags assigned". Tag instances are not listed as separate objects.

<<img>> Tags tab and TAGS column in the RE XLSX structure file

Create Tag

Tags can be created in a project in the Database Explorer. They appear under the Tags node, or Labels in BigQuery projects.

Click on the three-dot menu next to Tags, click "Create New," and proceed to add details in the Properties Panel. Alternatively, select the Tags node or a specific tag and click the + icon at the bottom of the Database Explorer panel.

You do not have to create a tag up front. Typing a new key (and value) directly on an object creates the project-level tag instance and assigns it in one step.

Manage Tag Properties

Tag properties can be maintained in the Properties panel for a selected Tag. These include

• Schema - Snowflake only

• Name (key)

• Value - Databricks and BigQuery only. Optional; leave blank to create a key-only tag

• List of values - Snowflake only. Leave this blank to allow any-value tags

• Color (for display in SqlDBM)

• Description (DDL comment) - Snowflake only

• Tagged Objects (for reference)

Because Snowflake tags are schema-qualified, they are displayed as schema_name.tag_name in the Database Explorer. Databricks tags and BigQuery labels use a flat namespace and are displayed as key : value, or as key alone for key-only Databricks tags.

<<img>> Tag Properties panel for a Databricks tag and a BigQuery label (Key / Value, no Schema or List of values)

Tag naming rules and limits

Each platform enforces its own rules on tag keys and values. SqlDBM validates as you type: invalid input disables the Add button, and the button re-enables as soon as the input is corrected. Hover the (i) icon next to the Key and Value fields to see the rules for your platform.

Name mapping, case standards, and glossary functionality are not applied to tags and labels.

Edit and delete tags

If you edit a tag instance that is already assigned to one or more objects, a confirmation dialog lists the affected objects and offers three choices:

• Update tag - the instance is updated and every existing assignment reflects the new key/value. Forward-engineered DDL for each assigned object changes accordingly.

• Create new tag - a new instance is created with the edited values. It is not assigned to anything, and existing assignments are unchanged.

• Cancel - nothing changes.

If the instance has no assignments, the edit is applied without a confirmation dialog.

To delete a tag, use the three-dot context menu > Delete, or select the tag and click the trash bin icon at the bottom of the panel. An unassigned tag is deleted immediately. If the tag is assigned to one or more objects, a confirmation dialog warns that deleting the tag will also delete all of its assignments.

<<img>> "Update tag / Create new tag / Cancel" and "Delete tag?" confirmation dialogs

Forward engineer tags

Each platform emits tags differently, and SqlDBM follows the native pattern for each.

Snowflake

Tag objects and assignments can be deployed to Snowflake databases through the Forward Engineer screen.

• Create - will generate DDL for creating the Tag

• Apply tags - will apply tags on database objects being generated

• Drop - without "Create" will generate drop statements for existing tags. Together with "Create," will generate a "CREATE OR REPLACE" statement for Tag objects.

Databricks

There is no CREATE TAG statement in Databricks, so tag instances have no DDL of their own. Tag assignments are emitted as separate ALTER ... SET TAGS statements after the object's CREATE statement - tags are never inlined into CREATE.

CREATE TABLE main.sales.orders
(
  order_id BIGINT,
  customer_email STRING
);

ALTER TABLE main.sales.orders
SET TAGS ('env' = 'prod', 'team' = 'data-engineering');

ALTER SCHEMA main.sales
SET TAGS ('domain' = 'finance');

ALTER VIEW main.sales.v_orders
SET TAGS ('status' = 'certified');

ALTER MATERIALIZED VIEW main.sales.mv_daily
SET TAGS ('refresh' = 'daily');

Databricks does not allow tagging multiple columns in a single ALTER TABLE command, so each tagged column gets its own statement. A key-only tag is emitted without a value.

ALTER TABLE main.sales.orders
ALTER COLUMN customer_email
SET TAGS ('pii' = 'high');

ALTER TABLE main.sales.orders
SET TAGS ('pii');

Updating tags. SET TAGS is an upsert - it adds new keys and updates the values of existing keys without affecting other tags on the object. The generated ALTER script therefore contains only the tags you added or changed.

Removing tags. Databricks has explicit removal syntax:

ALTER TABLE main.sales.orders
UNSET TAGS ('env');

ALTER TABLE main.sales.orders
ALTER COLUMN customer_email
UNSET TAGS ('pii');

BigQuery

There is no CREATE LABEL statement in BigQuery. Label assignments are emitted inline in the object's OPTIONS (labels = [...]) clause, matching native BigQuery DDL - no separate deployment step is needed.

CREATE TABLE `project.dataset.my_table`
(
  id INT64,
  name STRING
)
OPTIONS (
  labels = [("env", "prod"), ("team", "data-engineering")]
);

Labels are not part of CREATE SCHEMA DDL in BigQuery, so dataset labels are emitted through ALTER SCHEMA:

ALTER SCHEMA `project.dataset`
SET OPTIONS (
  labels = [("env", "prod"), ("team", "data-engineering")]
);

Updating labels. BigQuery has no ADD LABEL or SET LABEL syntax. Label assignments on an existing object are updated by replacing the entire labels array, so the generated script always includes every label currently assigned to the object - not only the one that changed.

Removing labels. There is no DROP LABEL syntax. A removed label is expressed by re-issuing SET OPTIONS with the remaining labels only. To drop every label from an object, pass an empty array:

ALTER TABLE `project.dataset.my_table`
SET OPTIONS (
  labels = []
);

Taggable objects

The following objects can be tagged:

BigQuery does not support labels at the column level. BigQuery labels apply to datasets, tables, views, and materialized views only. For column-level metadata in BigQuery, use column descriptions or BigQuery policy tags - both separate features outside the scope of labels.

Tagging stops at the schema level in all three platforms. Catalog-level and database-level tags are not modeled in SqlDBM.

Tag features

Beyond handling Tag DDL in Reverse and Forward Engineering, the following features are available by request to extend the utility of tagged objects.

Tags on the diagram

Tags can be viewed and maintained visually on SqlDBM diagrams.

Tagged objects are depicted with a tag icon. Column tags are displayed to the right of the column, while table tags are shown on the bottom right of the table. Hover the tag icon to see the assigned tags as key : value, or key alone for key-only Databricks tags. Click the tag icon to open that tag's Properties editor.

To assign a tag, right-click on the object and navigate to the "Add Tag" sub-menu to select the desired tag and tag value.

For any-value tags (those without a specified list of values), type the value in instead of selecting from a list.

<<img>> Tag icons on the diagram in a Databricks project, including a key-only tag on hover

Tags in object properties

Every taggable object has a Tags (or Labels) section in its Properties editor, containing a Key field, a Value field, and an Add button.

• The Key field suggests tag instances that already exist in the project. Once a key is chosen, the Value field suggests values already used with that key.

• If a matching tag instance already exists, clicking Add creates an assignment from that instance. If no match exists, SqlDBM creates the instance and the assignment at the same time. Only the current object is affected.

• Each assigned tag is shown as its own row displaying key : value, or just key for a key-only Databricks tag, with an x control to remove it.

• The key of an assigned row cannot be edited in place - remove the row and add a new tag instead. The value can be edited inline; doing so affects only the current object.

• Clicking x removes the assignment from the current object immediately, with no confirmation. The tag instance itself is not deleted and remains available for other objects.

Column tags (Snowflake and Databricks) are managed the same way from the Column Properties editor or the column grid.

Bulk assignment

Select multiple objects on the diagram to open the bulk Object Properties editor, which includes the same Tags section. You can assign an existing tag to every selected object at once, or type a new key and value to create the tag and assign it everywhere in a single step. A tag can only be removed in bulk if it is assigned to every selected object - if even one selected object does not carry the tag, it is not offered for removal there.

<<img>> Tags section in the object Properties editor and in the bulk editor

Diagram filter

Diagram filters can use Tag names and values in conjunction with existing Color and (metadata) Flag filters. Ensure that the filter criteria (AND / OR) is set according to expectations.

When a tag filter is active, the diagram displays only objects with a matching assignment - either on the object itself or on any of its columns. The filter matches a full key : value pair, or a key alone for key-only Databricks tags.

Database documentation

Tags are available in Database Documentation and can be used for reference and search.

Select Tags from the DB Documentation Properties panel on the right of the screen to enable the column. The Tags (Labels) option is enabled by default and controls whether each object's assigned tags are rendered in its documentation entry. Tags are displayed as key : value, or as key alone for key-only Databricks tags. Tag instances with no assignments are not shown.

To search for a Tag name or value, use the search field on the top left of the screen.

Report page

Tags appear in the DB Documentation navigation tree and can be selected to open their own page, showing the tag value and every object and column it is assigned to, with links. When you open any tagged object, its assignments are listed in the object's Details tab as key : value pairs, each hyperlinked to that tag's details page. In Snowflake and Databricks projects, column tags are shown per column.

<<img>> Report page - tag details with related objects, and an object Details tab showing tag assignments

Compare and Merge

Tag instances are listed under the Project level objects tab, alongside other project-level constructs - new tags marked as added, edited tags as updated, removed tags as deleted. Tag assignments are listed at the object level, under the object they belong to. An object is marked as updated when tags are added to or removed from it, including changes to its column tags.

<<img>> Compare and Merge summary showing tag instances under Project level objects

Column lineage analysis

In Snowflake and Databricks projects, tags assigned to views and view columns are visible in the column lineage analysis diagram. BigQuery labels are not displayed in column lineage analysis.

Errors and warnings

Keys and values entered in the interface are validated as you type, so invalid tags cannot be created there. Tags introduced through Reverse Engineering - DDL import, Direct Connect, or XLSX upload - are validated on import instead, and any violation raises an entry in Errors & Warnings identifying the affected object (including table.column for column tags), the invalid key or value, and the specific rule that was broken.

Validation is performed per tag pair rather than per object or per cell, so one malformed tag never blocks the import of the other valid tags on the same object.

Platform differences at a glance

Out of scope

• Catalog-level and database-level tags - SqlDBM tagging stops at the schema level in all three platforms.

• Databricks volumes, registered models, and functions - Databricks supports tagging these objects, but they are not modeled in SqlDBM.

• Databricks governed tags (tag policies) - an account-level governance feature that is not SQL-manageable, so it cannot be modeled or forward-engineered. The assignment syntax is identical to freeform tags, so Reverse and Forward Engineering are unaffected. Note that a generated script may still fail at execution time in a workspace whose tag policy rejects a key or value, or where the executing user lacks permission to assign it - this is expected Databricks behavior, not a problem with the script.

• BigQuery policy tags - a separate column-level access control feature, unrelated to labels, that cannot be set through CREATE TABLE DDL.

See also:

• Governance Fields

• Governance Pages