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"
      },
      {
        "name": "priority",
        "data_type": "INT64"
      }
    ]
  }'

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"},
            {"name": "priority", "data_type": "INT64"},
        ]
    },
)

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" },
      { name: "priority", data_type: "INT64" },
    ],
  }),
});

{
  "database": "acme_corp",
  "tenant_id": "acme_corp",
  "added_fields": ["region", "priority"]
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Schema conflict: field \"region\" already exists in the schema with a different definition. Resubmitting a field with its existing definition is accepted as a no-op, but an existing field cannot be modified. See https://docs.hydradb.com/api-reference/v2/endpoint/patch-metadata-schema for usage details. Re-send the field with its existing definition to make this a no-op, or use a different field name."
  },
  "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"
      },
      {
        "name": "priority",
        "data_type": "INT64"
      }
    ]
  }'

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"},
            {"name": "priority", "data_type": "INT64"},
        ]
    },
)

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" },
      { name: "priority", data_type: "INT64" },
    ],
  }),
});

{
  "database": "acme_corp",
  "tenant_id": "acme_corp",
  "added_fields": ["region", "priority"]
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Schema conflict: field \"region\" already exists in the schema with a different definition. Resubmitting a field with its existing definition is accepted as a no-op, but an existing field cannot be modified. See https://docs.hydradb.com/api-reference/v2/endpoint/patch-metadata-schema for usage details. Re-send the field with its existing definition to make this a no-op, or use a different field name."
  },
  "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. SDK methods: client.databases.update_metadata_schema() (Python) and client.databases.updateMetadataSchema() (TypeScript). GET /databases/{database}/metadata-schema returns the current schema in the same field shape.

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

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"
      },
      {
        "name": "priority",
        "data_type": "INT64"
      }
    ]
  }'

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"},
            {"name": "priority", "data_type": "INT64"},
        ]
    },
)

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" },
      { name: "priority", data_type: "INT64" },
    ],
  }),
});

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. A field that already exists with an identical definition is skipped, so you can resend your full field list.

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, contain only letters/numbers/underscores (up to 255 characters), 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`.
	Rejected with `400` on a new field. Dense semantic-search lanes can only be declared at database creation.
	Rejected with `400` on a new field. Sparse/BM25 search lanes can only be declared at database creation.

Rules

Existing field names cannot be reused with a different definition, case-insensitively. A field that differs from the existing one in type, max_length, or flags returns 409, as does one name declared twice in a request with different definitions. Resending a field with its identical definition is a no-op.
Total custom database metadata fields cannot exceed 32. Skipped fields do not count toward the new total.
Reserved names such as source_id, chunk_id, metadata, and document_metadata are rejected.
Resending an existing field that already has dense or sparse flags is a no-op.

Response

A success returns database, the deprecated tenant_id, and added_fields directly, without the success/data envelope. added_fields lists only the fields this call added, so an empty list means the database already had everything you sent. Errors use the standard error envelope.

{
  "database": "acme_corp",
  "tenant_id": "acme_corp",
  "added_fields": ["region", "priority"]
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Schema conflict: field \"region\" already exists in the schema with a different definition. Resubmitting a field with its existing definition is accepted as a no-op, but an existing field cannot be modified. See https://docs.hydradb.com/api-reference/v2/endpoint/patch-metadata-schema for usage details. Re-send the field with its existing definition to make this a no-op, or use a different field name."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

Errors

Status	When it happens
`400`	Invalid request body (`INVALID_INPUT`), empty `add_fields`, invalid field name/type, `ARRAY`, too many fields, or an embedding flag on a new field.
`404`	Database not found (`DATABASE_NOT_FOUND`).
`409`	A field conflicts with an existing field or with another entry in the same request, or the database changed during the request (retry this last case).
`500`	Saving the schema failed. Retry.

Apart from a malformed body and a missing database, this endpoint currently returns error.code: "INTERNAL_ERROR" for 400, 409, and 500 alike. Branch on the HTTP status and read error.message, which names the field and the rule it broke.

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:

[
  {
    "name": "region",
    "data_type": "VARCHAR",
    "max_length": 256
  }
]

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"

Start here

Databases

Context

Query

Connectors

Webhooks

Reference

Update Metadata Schema

Request

Path parameters

Body

Rules

Response

Errors

Authorizations

Path Parameters

Body

Response

​Request

​Path parameters

​Body

​Rules

​Response

​Errors

​Related

Authorizations

Path Parameters

Body

Response

Request

Path parameters

Body

Rules

Response

Errors

Related