Create Database

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
  }
}

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 a collection. 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 with POST /databases after 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.

You can define a custom schema at database creation to enable exact-match metadata filtering (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.

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

Authorization

string

header

required

API key sent as a Bearer token: "Bearer prefix.secret"

Body

application/json

Database creation request

database

string

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"

database_metadata_schema

object[]

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

Example:

[
  {
    "data_type": "VARCHAR",
    "enable_analyzer": false,
    "enable_dense_embedding": true,
    "enable_match": true,
    "enable_sparse_embedding": false,
    "max_length": 256,
    "name": "category"
  }
]

embeddings_dimension

integer

Override for the embedding vector dimension. Default: 1536.

Example:

1536

is_embeddings_tenant

boolean

Internal flag for embedding-only databases.

Example:

false

tenant_id

string

deprecated

deprecated: use database

Example:

"tenant_1234"

tenant_metadata_schema

object[]

deprecated

deprecated: use database_metadata_schema

Show child attributes

Response

data

object

Show child attributes

Example:

{
  "database": "acme_corp",
  "message": "Success",
  "status": "completed",
  "tenant_id": "tenant_1234"
}

error

object

Error message, empty string on success.

Show child attributes

Example:

{
  "code": "DATABASE_NOT_FOUND",
  "message": "Database not found"
}

API Documentation

Databases

Context

Query

Connectors

Miscellaneous

Request body

Successful response

What happens after database creation?

Defining metadata schema

Authorizations

Body

Response

​Request body

​Successful response

​What happens after database creation?

​Defining metadata schema

​Related Resources

Authorizations

Body

Response

Request body

Successful response

What happens after database creation?

Defining metadata schema

Related Resources