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
}
}
Databases
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
}
}
Creates an isolated database, optionally with a metadata schema. Creation is asynchronous: poll Database Status until
infra.ready_for_ingestion is true before you ingest or query.
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
}
}
Request body
| 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. | |
| Database-level metadata fields. See the schema field reference for field options. |
Metadata schema rules
- Existing field names and types cannot change. Update Metadata Schema can add fields later.
- Dense and sparse metadata search can only be enabled at database creation, with
enable_dense_embeddingandenable_sparse_embedding. - Each flag adds one vector field. A database can have at most six vector fields. Exceeding this limit or declaring an
ARRAYfield returns400.
After creation
- Wait for provisioning: Poll Database Status until
infra.ready_for_ingestionistrue. - Ingest: Start ingesting context. Ingesting with a new
collectionname creates that collection. Omittingcollectionuses the default collection, also created on first ingestion. No separate create call is needed. - Query: Check ingestion status, and query once sources show
graph_creation(searchable) orcompleted.
data.failed_databases from List Databases, address the reported issue, re-create the database with POST /databases, and poll status again before ingesting.
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
- After this: Database Status: poll until provisioning completes
- After this: Ingest Context: ingest once the database is ready
- Related: Update Metadata Schema: add metadata schema fields later
- Related: Delete Database: remove the database and everything in it
- Guide: Databases and Collections: choose database and collection scopes
- Guide: Metadata Filters: field options, ingestion, and filtering examples
Authorizations
Send your API key as Authorization: Bearer <your_api_key>.
Body
application/json
Database creation request
Name of the database to create. Formerly tenant_id, which is still accepted.
Example:
"acme_corp"
Database-level metadata fields for exact-match filtering and semantic or BM25 search. Field names cannot change after 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 details on failure, or null on success.
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": "sub_tenant_4567", "tenant_id": "tenant_1234", "warnings": [ { "code": "acl_ignored_by_connector_enforcement", "message": "This connector enforces ACL, so the request's acl was ignored." } ] }
Whether the request succeeded.
Example:
true
Was this page helpful?