Update Metadata Schema

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
      }
    ]
  }'

import requests

response = requests.patch(
    "https://api.hydradb.com/databases/acme_corp/metadata-schema",
    headers={
        "Authorization": f"Bearer {HYDRA_DB_API_KEY}",
        "API-Version": "2",
        "Content-Type": "application/json",
    },
    json={
        "add_fields": [
            {"name": "region", "data_type": "VARCHAR", "enable_match": True},
            {
                "name": "summary_label",
                "data_type": "VARCHAR",
                "enable_dense_embedding": True,
                "enable_sparse_embedding": True,
            },
        ]
    },
)

const response = await fetch("https://api.hydradb.com/databases/acme_corp/metadata-schema", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HYDRA_DB_API_KEY}`,
    "API-Version": "2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    add_fields: [
      { name: "region", data_type: "VARCHAR", enable_match: true },
      {
        name: "summary_label",
        data_type: "VARCHAR",
        enable_dense_embedding: true,
        enable_sparse_embedding: true,
      },
    ],
  }),
});

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "CONFLICT",
    "message": "field \"region\" already exists in the schema"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

PATCH

databases

{database}

metadata-schema

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
      }
    ]
  }'

import requests

response = requests.patch(
    "https://api.hydradb.com/databases/acme_corp/metadata-schema",
    headers={
        "Authorization": f"Bearer {HYDRA_DB_API_KEY}",
        "API-Version": "2",
        "Content-Type": "application/json",
    },
    json={
        "add_fields": [
            {"name": "region", "data_type": "VARCHAR", "enable_match": True},
            {
                "name": "summary_label",
                "data_type": "VARCHAR",
                "enable_dense_embedding": True,
                "enable_sparse_embedding": True,
            },
        ]
    },
)

const response = await fetch("https://api.hydradb.com/databases/acme_corp/metadata-schema", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HYDRA_DB_API_KEY}`,
    "API-Version": "2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    add_fields: [
      { name: "region", data_type: "VARCHAR", enable_match: true },
      {
        name: "summary_label",
        data_type: "VARCHAR",
        enable_dense_embedding: true,
        enable_sparse_embedding: true,
      },
    ],
  }),
});

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "CONFLICT",
    "message": "field \"region\" already exists in the schema"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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 -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
      }
    ]
  }'

import requests

response = requests.patch(
    "https://api.hydradb.com/databases/acme_corp/metadata-schema",
    headers={
        "Authorization": f"Bearer {HYDRA_DB_API_KEY}",
        "API-Version": "2",
        "Content-Type": "application/json",
    },
    json={
        "add_fields": [
            {"name": "region", "data_type": "VARCHAR", "enable_match": True},
            {
                "name": "summary_label",
                "data_type": "VARCHAR",
                "enable_dense_embedding": True,
                "enable_sparse_embedding": True,
            },
        ]
    },
)

const response = await fetch("https://api.hydradb.com/databases/acme_corp/metadata-schema", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.HYDRA_DB_API_KEY}`,
    "API-Version": "2",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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`, `ARRAY`, or friendly aliases such as `string`, `integer`, `float`, `boolean`, `object`, `array`. Defaults to `VARCHAR`.
	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

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "CONFLICT",
    "message": "field \"region\" already exists in the schema"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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.

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_analyzer": false,
    "enable_dense_embedding": true,
    "enable_match": true,
    "enable_sparse_embedding": false,
    "max_length": 256,
    "name": "category"
  }
]

Response

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"

Create Database List Databases

⌘I

​Request

​Path parameters

​Body

​Rules

​Response

​Errors

​Related

Authorizations

Path Parameters

Body

Response

Request

Path parameters

Body

Rules

Response

Errors

Related