response = client.databases.create(
database="my_first_database",
database_metadata_schema=[
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": True,
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": True,
"enable_sparse_embedding": True,
},
],
)
const response = await client.databases.create({
database: "my_first_database",
databaseMetadataSchema: [
{
name: "category",
dataType: "VARCHAR",
maxLength: 256,
enableMatch: true,
},
{
name: "product_description",
dataType: "VARCHAR",
maxLength: 4096,
enableDenseEmbedding: true,
enableSparseEmbedding: true,
},
],
});
curl -X POST 'https://api.hydradb.com/databases' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "my_first_database",
"database_metadata_schema": [
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": true
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": true,
"enable_sparse_embedding": true
}
]
}'
{
"success": true,
"data": {
"status": "accepted",
"database": "my_first_database",
"message": "Database creation started in the background. Use GET /databases/status?database=... to check progress."
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_ALREADY_EXISTS",
"message": "Database ID already exists"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
Databases
Create Database
Creates a space for storing context.
POST
/
databases
response = client.databases.create(
database="my_first_database",
database_metadata_schema=[
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": True,
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": True,
"enable_sparse_embedding": True,
},
],
)
const response = await client.databases.create({
database: "my_first_database",
databaseMetadataSchema: [
{
name: "category",
dataType: "VARCHAR",
maxLength: 256,
enableMatch: true,
},
{
name: "product_description",
dataType: "VARCHAR",
maxLength: 4096,
enableDenseEmbedding: true,
enableSparseEmbedding: true,
},
],
});
curl -X POST 'https://api.hydradb.com/databases' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "my_first_database",
"database_metadata_schema": [
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": true
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": true,
"enable_sparse_embedding": true
}
]
}'
{
"success": true,
"data": {
"status": "accepted",
"database": "my_first_database",
"message": "Database creation started in the background. Use GET /databases/status?database=... to check progress."
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_ALREADY_EXISTS",
"message": "Database ID already exists"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
response = client.databases.create(
database="my_first_database",
database_metadata_schema=[
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": True,
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": True,
"enable_sparse_embedding": True,
},
],
)
const response = await client.databases.create({
database: "my_first_database",
databaseMetadataSchema: [
{
name: "category",
dataType: "VARCHAR",
maxLength: 256,
enableMatch: true,
},
{
name: "product_description",
dataType: "VARCHAR",
maxLength: 4096,
enableDenseEmbedding: true,
enableSparseEmbedding: true,
},
],
});
curl -X POST 'https://api.hydradb.com/databases' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "my_first_database",
"database_metadata_schema": [
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
"enable_match": true
},
{
"name": "product_description",
"data_type": "VARCHAR",
"max_length": 4096,
"enable_dense_embedding": true,
"enable_sparse_embedding": true
}
]
}'
Request body
database and collection are the current field names (formerly tenant_id and sub_tenant_id). The old names remain accepted as deprecated aliases for full backward compatibility.| Name | Description |
|---|---|
Account-scoped database identifier. Use a stable, case-sensitive ID up to 25 characters; prefer lowercase letters, numbers, and underscores for portability. Formerly tenant_id; the tenant_id alias is still accepted (deprecated). | |
Defines database-level metadata fields. See the Scoping using metadata guide for detailed schema parameters. Formerly tenant_metadata_schema; the tenant_metadata_schema alias is still accepted (deprecated). (default=null) |
Successful response
Always check if a database is ready before using it. Use Database Status to check.{
"success": true,
"data": {
"status": "accepted",
"database": "my_first_database",
"message": "Database creation started in the background. Use GET /databases/status?database=... to check progress."
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_ALREADY_EXISTS",
"message": "Database ID already exists"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
What happens after database creation?
- Create the database with
POST /databases - Default collection: No collection exists until your first write. The first time you ingest without an explicit
collection, HydraDB creates the database’s default collection, which then stores all context written without acollection. Create additional collections at any time to scope data to users, teams, or projects. - Retry failed databases: If a database appears in
data.failed_databases, re-create that database withPOST /databasesafter addressing the reported issue. Poll status again before ingestion. - Start ingesting context once databases are ready
- Check status of ingestion. Start querying the database once the recently ingested sources show
completed
Defining metadata schema
Schema field names are immutable after database creation. You can add per-document free-form metadata fields at ingestion time, and add new database-level fields later with Update Metadata Schema, but updates are additive only: no delete, rename, type change, or Milvus backfill for newly added dense/sparse metadata lanes. Plan your schema carefully before creating the database.
enable_match) or semantic/BM25 search over metadata text fields (enable_dense_embedding / enable_sparse_embedding).
For detailed parameters, valid data types, limits, shorthand flags, and comprehensive examples, see the metadata guide.
Related Resources
- Next: Database Status - poll until provisioning completes
- Next: Ingest Context - start ingesting data once status is ready
- Related: Update Metadata Schema - add metadata schema fields later
- Related: Delete Database - teardown
- Read more: Concepts → Multi-Tenant Support
- Read more: Usage → Metadata
Authorizations
API key sent as a Bearer token: "Bearer prefix.secret"
Body
application/json
Database creation request
Database is the canonical v2 name; TenantID is its deprecated alias and remains fully accepted. The TenantAliases middleware reconciles them before this binds, so TenantID is always populated.
Example:
"acme_corp"
Defines database-level metadata fields for exact-match filtering and semantic/BM25 search. Canonical name; tenant_metadata_schema is a deprecated alias. Schema field names are immutable after database creation.
Show child attributes
Show child attributes
Example:
[
{
"data_type": "VARCHAR",
"enable_dense_embedding": true,
"enable_match": true,
"enable_sparse_embedding": false,
"max_length": 256,
"name": "category"
}
]
Override for the embedding vector dimension. Default: 1536.
Example:
1536
Internal flag for embedding-only databases.
Example:
false
deprecated: use database
Example:
"tenant_1234"
deprecated: use database_metadata_schema
Show child attributes
Show child attributes
Response
OK
Show child attributes
Show child attributes
Example:
{
"database": "acme_corp",
"message": "Success",
"status": "completed",
"tenant_id": "tenant_1234"
}
Error message, empty string on success.
Show child attributes
Show child attributes
Example:
{
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
}
Show child attributes
Show child attributes
Example:
{
"collection": "team_docs",
"database": "acme_corp",
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"source_type": "file",
"sub_tenant_id": "sub_tenant_4567",
"tenant_id": "tenant_1234"
}
Whether the request succeeded.
Example:
true
Was this page helpful?