Metadata

1. What it is

Metadata is structured data attached to knowledge and memories. It lets you narrow recall to a known scope before semantic retrieval runs. Use metadata when you already know a concrete attribute of the content you want back - for example:

environment: "production"
document_type: "runbook"
compliance_framework: "SOC2"
status: "published"

Metadata filtering is different from semantic search. Semantic search finds content by meaning; metadata filtering narrows the candidate set using structured fields.

2. What it does

When you pass metadata_filters to recall, HydraDB uses those filters to narrow the candidate set before ranking retrieved chunks. This gives you more predictable recall when the query needs to stay inside a known slice of data. For example, this query:

{
  "query": "How does authentication work?",
  "metadata_filters": {
    "compliance_framework": "SOC2"
  }
}

does not ask HydraDB to semantically interpret “SOC2”. It narrows recall to content tagged with that metadata value, then runs retrieval inside that filtered set. Use metadata filters for hard constraints. Use semantic recall for fuzzy or conceptual matching.

3. When to use it

Use metadata filtering when:

The result must come from a known category, environment, customer tier, language, status, or document type.
You need deterministic narrowing alongside semantic recall.
You want to avoid mixing content from different operational scopes.
You want to keep draft, archived, internal, or region-specific content out of a user-facing answer.

Do not use metadata filtering for:

Synonyms
Partial matches
Fuzzy intent
Conceptual similarity
Ranking preferences
Range or contains-style operators

Those belong in the query, recall mode, or downstream reranking logic.

4. How it works

1. Define filterable fields

Filterable top-level metadata fields are defined in the tenant metadata schema. Plan filterable fields before ingestion. If your application needs to filter on a field, define it in the tenant metadata schema before writing data that depends on that filter, and enable matching for it.

2. Attach metadata when writing data

Attach metadata when adding knowledge or memories. Use metadata for stable attributes that you expect to filter on later, such as:

{
  "environment": "production",
  "document_type": "runbook",
  "status": "published"
}

3. Filter during recall

Pass metadata_filters during recall to narrow the candidate set.

{
  "tenant_id": "acme_corp",
  "query": "How do I rotate API keys?",
  "metadata_filters": {
    "environment": "production",
    "document_type": "runbook"
  }
}

Recall then runs over candidates matching the filter.

5. Key concepts

Tenant metadata schema

The tenant metadata schema defines which top-level metadata fields can be matched during recall. Use it for fields that your application will filter on repeatedly, such as:

environment
language
region
document_type
status
customer_tier

For complete tenant_metadata_schema examples, supported field types, and advanced configuration options, see Create Tenant API Reference.

`enable_match`

A metadata field must be match-enabled to be usable in metadata_filters. If a field is stored but not match-enabled, do not rely on it for deterministic filtering.

`metadata_filters`

metadata_filters is the recall parameter used to apply deterministic filters. Example:

{
  "metadata_filters": {
    "status": "published",
    "language": "en"
  }
}

Multiple keys are treated as structured filter constraints; use semantic recall or downstream reranking for fuzzy, range, or preference-based matching. Use it when the filter value is known exactly. Operators such as range, contains, or fuzzy matching are not supported.

`metadata` vs `additional_metadata`

HydraDB exposes two metadata fields on every source object. Both are filterable at recall, but via different keys in metadata_filters and with different performance characteristics:

metadata — schema-aligned tenant-level fields. Each key must be declared in tenant_metadata_schema with enable_match: true at tenant creation. Filter via top-level keys in metadata_filters. Pre-filtered in the vector store, so this is the fast path.
additional_metadata — free-form document-level fields. Filter by nesting under the additional_metadata key inside metadata_filters (canonical) or document_metadata (legacy alias). Applied post-retrieval, with the engine over-fetching (~3x) to compensate — slower than tenant-level filters.

{
  "metadata_filters": {
    "environment": "production",
    "additional_metadata": { "author": "alice" }
  }
}

If a field will be filtered on every query (hot path), put it in `metadata` and declare it in the tenant schema with `enable_match: true`. For ad-hoc or per-document fields, use `additional_metadata`.

### Metadata filtering vs `sub_tenant_id`

Use `sub_tenant_id` to partition data by user, workspace, team, or another logical scope.

Use `metadata_filters` to narrow results inside that scope.

They are complementary:

```text
tenant_id      -> primary scope
sub_tenant_id  -> logical partition inside the tenant
metadata       -> deterministic filters inside that partition

Do not use metadata filters as a substitute for choosing the right tenant or sub-tenant.

6. Minimal working example

This example shows the full pattern:

Create a tenant with a filterable metadata field.
Write content tagged with that metadata.
Recall content matching that metadata.

1. Define filterable metadata

{
  "tenant_id": "acme_corp",
  "tenant_metadata_schema": [
    {
      "name": "compliance_framework",
      "data_type": "VARCHAR",
      "enable_match": true
    }
  ]
}

The exact tenant creation request may include additional fields depending on your setup. See the Create Tenant API Reference for the complete schema.

2. Attach metadata when writing content

{
  "tenant_id": "acme_corp",
  "app_knowledge": [
    {
      "tenant_id": "acme_corp",
      "sub_tenant_id": "default",
      "id": "auth-controls-001",
      "kind": "knowledge_base",
      "provider": "internal",
      "external_id": "auth-controls-001",
      "fields": {
        "kind": "knowledge_base",
        "title": "Authentication controls",
        "body": "Authentication controls are reviewed quarterly for SOC2."
      },
      "metadata": {
        "compliance_framework": "SOC2"
      }
    }
  ]
}

Use the metadata field names you planned in the tenant metadata schema.

3. Recall with `metadata_filters`

result = client.recall.full_recall(
    tenant_id="acme_corp",
    query="How does authentication control review work?",
    metadata_filters={
        "compliance_framework": "SOC2",
    },
)

const result = await client.recall.fullRecall({
  tenant_id: "acme_corp",
  query: "How does authentication control review work?",
  metadata_filters: {
    compliance_framework: "SOC2",
  },
});

Recall then runs over candidates matching the filter.

7. Recommended patterns

Published vs draft content

Use a status field when your application has both draft and published content.

{
  "metadata_filters": {
    "status": "published"
  }
}

This helps prevent draft content from appearing in user-facing answers.

Language-specific recall

Use a language field when your tenant contains multilingual content.

{
  "metadata_filters": {
    "language": "en"
  }
}

Environment-specific recall

If environment-specific content intentionally exists in the same tenant scope, use an environment field to narrow recall.

{
  "metadata_filters": {
    "environment": "production"
  }
}

For stronger separation between production and staging, prefer separate tenants. Use metadata only when the content is intentionally stored under the same tenant.

Document-type filtering

Use a document_type field when different source types should be retrieved differently.

{
  "metadata_filters": {
    "document_type": "runbook"
  }
}

8. Common mistakes

Filtering on fields that were not configured for matching.
If a field is not declared and match-enabled, HydraDB ignores that filter. Plan filterable fields before ingestion so your filters actually narrow recall. Using metadata filters for fuzzy search.
Metadata filters are for structured constraints. Use semantic recall for fuzzy meaning, synonyms, or conceptual matches. Trying to use metadata as a tenant boundary.
Metadata narrows results inside a scope. It should not replace tenant_id or sub_tenant_id for scoping customers, users, or workspaces. Adding filterable fields too late.
If your application needs deterministic filtering on a field, plan it early and declare it in the tenant metadata schema before ingestion. Confusing metadata fields across endpoints.
Metadata is always passed as plain JSON objects using the field names metadata and additional_metadata. Check the relevant endpoint reference for which fields are supported. Over-filtering.
Too many filters can remove the chunk that would have answered the question. Start with the minimum hard constraints needed, then tune.

Recall - using metadata_filters during retrieval
Memories - metadata fields on memory items
Multi-Tenant Support - tenant and sub-tenant scoping
Create Tenant API Reference - defining tenant metadata schema
Full Recall API Reference - using metadata filters in recall

Get Started

Essentials

Plugins

For Agents

1. What it is

2. What it does

3. When to use it

4. How it works

1. Define filterable fields

2. Attach metadata when writing data

3. Filter during recall

5. Key concepts

Tenant metadata schema

`enable_match`

`metadata_filters`

`metadata` vs `additional_metadata`

6. Minimal working example

1. Define filterable metadata

2. Attach metadata when writing content

3. Recall with `metadata_filters`

7. Recommended patterns

Published vs draft content

Language-specific recall

Environment-specific recall

Document-type filtering

8. Common mistakes

​1. What it is

​2. What it does

​3. When to use it

​4. How it works

​1. Define filterable fields

​2. Attach metadata when writing data

​3. Filter during recall

​5. Key concepts

​Tenant metadata schema

​enable_match

​metadata_filters

​metadata vs additional_metadata

​6. Minimal working example

​1. Define filterable metadata

​2. Attach metadata when writing content

​3. Recall with metadata_filters

​7. Recommended patterns

​Published vs draft content

​Language-specific recall

​Environment-specific recall

​Document-type filtering

​8. Common mistakes

​Related

1. What it is

2. What it does

3. When to use it

4. How it works

1. Define filterable fields

2. Attach metadata when writing data

3. Filter during recall

5. Key concepts

Tenant metadata schema

`enable_match`

`metadata_filters`

`metadata` vs `additional_metadata`

6. Minimal working example

1. Define filterable metadata

2. Attach metadata when writing content

3. Recall with `metadata_filters`

7. Recommended patterns

Published vs draft content

Language-specific recall

Environment-specific recall

Document-type filtering

8. Common mistakes

Related