Update Metadata Schema

Add new database metadata schema fields after database creation.

PATCH /databases/{database}/metadata-schema

cURL

curl -X PATCH 'https://api.hydradb.com/databases/acme_corp/metadata-schema' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "add_fields": [
      {
        "name": "region",
        "data_type": "VARCHAR",
        "enable_match": true
      },
      {
        "name": "summary_label",
        "data_type": "VARCHAR",
        "enable_dense_embedding": true,
        "enable_sparse_embedding": true
      }
    ]
  }'

Success

{
  "database": "acme_corp",
  "added_fields": ["region", "summary_label"]
}

Use this endpoint to add new fields to a database’s database_metadata_schema.

This endpoint is additive only. It cannot delete fields, rename fields, or change the type/flags of existing fields.

cURL

curl -X PATCH 'https://api.hydradb.com/databases/acme_corp/metadata-schema' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "add_fields": [
      {
        "name": "region",
        "data_type": "VARCHAR",
        "enable_match": true
      },
      {
        "name": "summary_label",
        "data_type": "VARCHAR",
        "enable_dense_embedding": true,
        "enable_sparse_embedding": true
      }
    ]
  }'

Request

Path parameters

Name	Description
	Database whose metadata schema should be extended. Formerly tenant_id; the tenant_id alias is still accepted (deprecated).

Body

Name	Description
	New metadata schema fields to append. Must contain at least one field.

Each add_fields[] item uses the same field shape as database_metadata_schema on Create Database:

Field	Description
	New metadata key. Must start with a letter or _, contain only letters/numbers/underscores, and not be a reserved system name.
	VARCHAR, BOOL, INT8, INT16, INT32, INT64, FLOAT, DOUBLE, JSON, or friendly aliases such as string, integer, float, boolean, object. Defaults to VARCHAR. ARRAY is not supported and is rejected with 400; for multi-value fields declare VARCHAR and store the values comma-joined.
	Max length for VARCHAR. Default 1024; maximum 65535.
	Enables the intended exact-match metadata filtering path for this field.
	Adds a dense semantic-search lane for a VARCHAR metadata field.
	Adds a sparse/BM25 search lane for a VARCHAR metadata field.
	Backward-compatible shorthand for enable_match: true. Prefer enable_match.

Rules

• Additions only.
• Existing field names cannot be reused, case-insensitively.
• Existing fields cannot be deleted or changed.
• Total custom database metadata fields cannot exceed 32.
• Reserved names such as source_id, chunk_id, metadata, and document_metadata are rejected.
• Dense/sparse embedding flags are only valid on VARCHAR fields.
• MongoDB indexes for enable_match fields are created before the merged schema is persisted.

This endpoint persists the updated schema and MongoDB filter indexes. It does not yet alter/backfill existing Milvus collections for newly added dense/sparse metadata fields. Create the desired semantic metadata fields before ingesting, or migrate/re-ingest into a database with the final schema if those fields must participate in semantic/BM25 metadata search.

Response

Success

{
  "database": "acme_corp",
  "added_fields": ["region", "summary_label"]
}

Errors

Status	When it happens
400	Invalid request body, empty add_fields, invalid field name/type, too many fields, embedding enabled on a non-VARCHAR field.
404	Database not found.
409	Field already exists or the update conflicts with stored database mapping/schema state.
500	Backend persistence or index creation failed.

Related

• Create Database
• Scoping using metadata
• Ingest Context
• Query

Authorizations

Authorization · string · header · required

API key sent as a Bearer token: "Bearer prefix.secret"

Path Parameters

database · string · required

Database identifier

Example:

"acme_corp"

Body

application/json

Metadata schema fields to add

add_fields · object[]

New metadata schema fields to add to the database. Additive only — no deletes, renames, or type changes.

Show child attributes

Example:

[
  {
    "data_type": "VARCHAR",
    "enable_dense_embedding": true,
    "enable_match": true,
    "enable_sparse_embedding": false,
    "max_length": 256,
    "name": "category"
  }
]

Response

200

application/json

OK

added_fields · string[]

Names of the metadata schema fields successfully added.

Example:

["region", "summary_label"]

database · string

Owning database. Formerly tenant_id; the tenant_id alias is still accepted (deprecated).

Example:

"acme_corp"

tenant_id · string · deprecated

Example:

"acme_corp"