> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Metadata Schema
> Add new database metadata schema fields after database creation.
export const Field = ({name, type, required, recommended}) => {
const label = required ? 'required' : recommended ? 'recommended' : null;
const typeLabel = typeof type === 'string' ? type : null;
const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean);
return
{name}
{required && *}
{recommended && ●}
{type && {type}}
{label &&
{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.
```bash cURL theme={"dark"}
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
}
]
}'
```
```python Python theme={"dark"}
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,
},
]
},
)
```
```typescript TypeScript theme={"dark"}
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](/api-reference/v2/endpoint/create-tenant):
| 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
```json Success theme={"dark"}
{
"database": "acme_corp",
"added_fields": ["region", "summary_label"]
}
```
```json Conflict theme={"dark"}
{
"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. |
## Related
* [Create Database](/api-reference/v2/endpoint/create-tenant)
* [Scoping using metadata](/essentials/v2/metadata)
* [Ingest Context](/api-reference/v2/endpoint/ingest-context)
* [Query](/api-reference/v2/endpoint/query)
## OpenAPI
````yaml api-reference/v2/openapi.json PATCH /databases/{database}/metadata-schema
openapi: 3.1.0
info:
contact:
email: support@hydradb.com
name: HydraDB Support
description: >-
HydraDB Application API — knowledge ingestion, search, and memory
management.
license:
name: Proprietary
title: HydraDB Application API
version: 0.1.0
servers:
- description: Production server
url: https://api.hydradb.com
security: []
externalDocs:
description: ''
url: ''
paths:
/databases/{database}/metadata-schema:
patch:
tags:
- database-management
summary: Update metadata schema
description: >-
Add new metadata schema fields to an existing database. Additive only —
existing fields cannot be deleted or retyped.
parameters:
- description: Database identifier
in: path
name: database
required: true
schema:
example: acme_corp
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/tenants.TenantMetadataSchemaUpdateRequest'
description: Metadata schema fields to add
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.metadataSchemaUpdateResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Conflict
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Internal Server Error
security:
- BearerAuth: []
components:
schemas:
tenants.TenantMetadataSchemaUpdateRequest:
properties:
add_fields:
description: >-
New metadata schema fields to add to the database. Additive only —
no deletes, renames, or type changes.
example:
- data_type: VARCHAR
enable_analyzer: false
enable_dense_embedding: true
enable_match: true
enable_sparse_embedding: false
max_length: 256
name: category
items:
$ref: '#/components/schemas/tenants.CustomPropertyDefinition'
type: array
uniqueItems: false
type: object
handler.metadataSchemaUpdateResponse:
properties:
added_fields:
description: Names of the metadata schema fields successfully added.
example:
- region
- summary_label
items:
type: string
type: array
uniqueItems: false
database:
description: >-
Owning database. Formerly `tenant_id`; the `tenant_id` alias is
still accepted (deprecated).
example: acme_corp
type: string
tenant_id:
deprecated: true
example: acme_corp
type: string
x-deprecated: 'true'
type: object
handler.ErrorResponse:
properties:
detail:
$ref: '#/components/schemas/handler.ErrorDetail'
description: Structured error detail with code, message, and deprecation hints.
example:
deprecated: true
deprecated_field: tenant_id
error_code: VALIDATION_ERROR
message: Request validation failed
preferred_field: database
success: true
type: object
tenants.CustomPropertyDefinition:
properties:
data_type:
$ref: '#/components/schemas/tenants.MilvusDataType'
description: Milvus data type for this metadata field.
example: VARCHAR
enable_analyzer:
description: >-
Whether to enable text analysis (tokenization) for BM25 search on
this field.
example: false
type: boolean
enable_dense_embedding:
description: Whether to enable semantic (dense) embedding search on this field.
example: true
type: boolean
enable_match:
description: Whether to enable exact-match filtering on this field.
example: true
type: boolean
enable_sparse_embedding:
description: Whether to enable BM25 (sparse) embedding search on this field.
example: false
type: boolean
max_length:
description: Maximum string length in bytes for VARCHAR fields.
example: 256
type: integer
name:
description: Field name. Immutable after database creation.
example: category
type: string
type: object
handler.ErrorDetail:
properties:
deprecated:
description: Whether this response concerns a deprecated field or route.
example: true
type: boolean
deprecated_field:
description: The deprecated field name.
example: tenant_id
type: string
error_code:
description: Machine-readable error classification code.
example: VALIDATION_ERROR
type: string
message:
description: Human-readable description of the error.
example: Request validation failed
type: string
preferred_field:
description: The canonical replacement for the deprecated field.
example: database
type: string
success:
description: Always false for error responses.
example: true
type: boolean
type: object
tenants.MilvusDataType:
enum:
- BOOL
- INT8
- INT16
- INT32
- INT64
- FLOAT
- DOUBLE
- VARCHAR
- JSON
- ARRAY
type: string
x-enum-varnames:
- DataTypeBool
- DataTypeInt8
- DataTypeInt16
- DataTypeInt32
- DataTypeInt64
- DataTypeFloat
- DataTypeDouble
- DataTypeVarchar
- DataTypeJSON
- DataTypeArray
securitySchemes:
BearerAuth:
bearerFormat: API key
description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
scheme: bearer
type: http
````