response = client.databases.create(
database="my_first_database",
database_metadata_schema=[
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
},
{
"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,
},
{
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
},
{
"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
}
}
Start here
Create Database
Create an isolated database, with an optional metadata schema.
POST
/
databases
response = client.databases.create(
database="my_first_database",
database_metadata_schema=[
{
"name": "category",
"data_type": "VARCHAR",
"max_length": 256,
},
{
"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,
},
{
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
},
{
"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,
},
{
"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,
},
{
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
},
{
"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 ID up to 255 characters of lowercase letters, digits, -, and _; anything else, including uppercase or spaces, returns 400. 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?
- Wait for provisioning: creation is asynchronous. Poll Database Status until
infra.ready_for_ingestionistrue. - 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_databasesfrom List Databases, re-create that database withPOST /databasesafter addressing the reported issue. Poll status again before ingestion. - Ingest: start ingesting context once the database is ready.
- Query: check ingestion status, and start querying once sources show
graph_creation(searchable) orcompleted.
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, or type change. Dense and sparse metadata lanes (
enable_dense_embedding, enable_sparse_embedding) can only be declared here, at creation. Plan your schema before you create the database.metadata fields you filter on, and to enable semantic/BM25 search over metadata text fields (enable_dense_embedding / enable_sparse_embedding). Each dense or sparse flag adds one vector field, so a field with both uses two; a database can have at most 6. Going over returns 400, as does declaring an ARRAY field.
For detailed parameters, valid data types, limits, and comprehensive examples, see the metadata guide.
Errors
Common codes:400 INVALID_INPUT (missing or invalid database, or an invalid schema), 403 FORBIDDEN (your plan’s database limit is reached), 409 DATABASE_ALREADY_EXISTS (the database is already in use; the deprecated POST /tenants route returns INVALID_INPUT instead), and 500 INTERNAL_ERROR (retry; if the message says the rollback also failed, delete the database first, then create it again). See Error Responses for the full list.
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_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"
}
Null on success; an object with code and message on failure.
Show child attributes
Show child attributes
Example:
null
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": "team_docs",
"tenant_id": "acme_corp"
}
Whether the request succeeded.
Example:
true
Was this page helpful?