HydraDB

https://docs.hydradb.com/get-started/v2/
Admin
HydraDB is a unified context substrate for stateful AI agents, delivering personalized context by...
Tokens:2,575
Snippets:23
Trust Score:7.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize HydraDB Client

Source: https://docs.hydradb.com/get-started/v2/quickstart

Initialize the client using an API key from the environment. Ensure the appropriate SDK is installed before execution.

```python
# Install: pip install "hydradb-sdk>=2,<3"
import os
from hydra_db import HydraDB

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])
```

```typescript
// Install: npm install @hydradb/sdk@^2
import { HydraDBClient } from "@hydradb/sdk";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY,
});
```

```bash
# No SDK needed — set your key once and reuse it.
export HYDRA_DB_API_KEY="your_api_key"

curl 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"
```

--------------------------------

### Apply Metadata Filters at Query Time

Source: https://docs.hydradb.com/get-started/v2/core-concepts

Example of applying hard filters to a query using the metadata_filters field.

```json
{
  "query": "latest pricing strategy",
  "metadata_filters": { "compliance_framework": "SOC2" }
}
```

--------------------------------

### Create, Ingest, and Query Database

Source: https://docs.hydradb.com/get-started/v2/quickstart

Perform a full lifecycle operation including database creation, ingestion, indexing verification, and semantic search.

```python
import json, time

database = "my_first_database"

# 1. Create a database.
client.databases.create(database=database)

# 2. Wait until the database can accept data.
while True:
    infra = client.databases.status(database=database).data.infra
    if infra.ready_for_ingestion:
        break
    time.sleep(5)

# 3. Ingest one memory into the default collection.
ingest = client.context.ingest(
    type="memory",
    database=database,
    memories=json.dumps([
        {"text": "User prefers detailed technical explanations and dark mode"}
    ]),
)

id = ingest.data.results[0].id

# 4. Wait until the memory is indexed.
while True:
    status = client.context.status(
        database=database,
        ids=[id],
    ).data.statuses[0]

    if status.indexing_status == "completed":
        break
    if status.indexing_status == "errored":
        raise RuntimeError(status.error_message)

    time.sleep(2)

# 5. Search memories.
results = client.query(
    database=database,
    type="memory",
    query="What does the user prefer?",
)

print(results.data.chunks)
```

```typescript
const database = "my_first_database";

// 1. Create a database.
await client.databases.create({ database: database });

// 2. Wait until the database can accept data.
while (true) {
  const { data } = await client.databases.status({ database: database });
  if (data?.infra.readyForIngestion) break;
  await new Promise((resolve) => setTimeout(resolve, 5_000));
}

// 3. Ingest one memory into the default collection.
const ingest = await client.context.ingest({
  type: "memory",
  database: database,
  memories: JSON.stringify([
    { text: "User prefers detailed technical explanations and dark mode" },
  ]),
});

const id = ingest.data.results[0].id;

// 4. Wait until the memory is indexed.
while (true) {
  const status = (await client.context.status({
    database: database,
    ids: [id],
  })).data.statuses[0];

  if (status.indexingStatus === "completed") break;
  if (status.indexingStatus === "errored") {
    throw new Error(status.errorMessage);
  }

  await new Promise((resolve) => setTimeout(resolve, 2_000));
}

// 5. Search memories.
const results = await client.query({
  database: database,
  type: "memory",
  query: "What does the user prefer?",
});

console.log(results.data.chunks);
```

```bash
export HYDRA_DB_API_KEY="your_api_key"
DATABASE="my_first_database"

# 1. Create a database.
curl -s -X POST 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d "{\"database\":\"${DATABASE}\"}"

# 2. Wait until the database can accept data.
until curl -s "https://api.hydradb.com/databases/status?database=${DATABASE}" \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  | jq -e '.data.infra.ready_for_ingestion' > /dev/null; do
  sleep 5
done

# 3. Ingest one memory into the default collection.
ID=$(curl -s -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=memory" \
  -F "database=${DATABASE}" \
  -F 'memories=[{"text":"User prefers detailed technical explanations and dark mode"}]' \
  | jq -r '.data.results[0].id')

# 4. Wait until the memory is indexed.
while true; do
  STATUS=$(curl -s -G 'https://api.hydradb.com/context/status' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    --data-urlencode "database=${DATABASE}" \
    --data-urlencode "ids=${ID}")

  INDEXING_STATUS=$(echo "$STATUS" | jq -r '.data.statuses[0].indexing_status')

  if [ "$INDEXING_STATUS" = "completed" ]; then break; fi
  if [ "$INDEXING_STATUS" = "errored" ]; then
    echo "$STATUS" | jq -r '.data.statuses[0].error_message'
    exit 1
  fi

  sleep 2
done

# 5. Search memories.
curl -s -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF | jq '.data.chunks'
{
  "database": "${DATABASE}",
  "type": "memory",
  "query": "What does the user prefer?"
}
EOF
```

--------------------------------

### Define Metadata at Ingestion

Source: https://docs.hydradb.com/get-started/v2/core-concepts

Structure for defining schema-based metadata and free-form additional metadata during document ingestion.

```json
{
  "metadata": { "compliance_framework": "SOC2", "region": "us" },
  "additional_metadata": {
    "owner": "sarah.chen@acme.com",
    "status": "approved"
 }
}
```
Tokens:
Raw