Filter by metadata

Metadata is a set of key and value pairs that you attach to a memory. You can then filter a search by those pairs. Metadata values must be strings, integers or floats.

These examples reuse client and a scope named alice, built as in Scope memories. The Go and Java examples take the client and scope values they use as parameters. The Go examples also take ctx.

Add metadataCopy Anchor Link

Pass metadata to add. The server rejects a value that is a boolean, null, an object or an array. It answers HTTP 400 with the code VALIDATION_FAILED.

client.add(
    "Order A-1001 shipped",
    scope=alice,
    metadata={"order_id": "A-1001", "total": 42.5, "priority": 2},
)

Filter a searchCopy Anchor Link

Pass metadata_filter to search. The filter combines with your scope and your query.

1. Write a filter object. A plain value means equality: {"order_id": "A-1001"}.
2. Use an operator object to compare: {"priority": {"$gte": 2}}.
3. Pass the object as metadata_filter.

results = client.search(
    "shipped orders",
    scope=alice,
    metadata_filter={"priority": {"$gte": 2}},
)

TypeScript names the option metadataFilter. Go and C# use the WithMetadataFilter method. Java uses withMetadataFilter.

OperatorsCopy Anchor Link

The table lists the filter operators, what each one means, and the value type each one accepts.

The four comparison operators $gt, $gte, $lt and $lte compare numbers. They do not compare strings. Operators on the same field combine with AND. This filter matches a priority from 1 to 3:

metadata_filter = {"priority": {"$gte": 1, "$lte": 3}}

A filter can nest to a depth of 5 and hold up to 50 nodes.

Handle the unsupported operatorCopy Anchor Link

The $contains operator is not supported. A search that uses it fails with HTTP 422 and the code CONTAINS_NOT_SUPPORTED. The SDK raises its unprocessable error.

from smritea import SmriteaUnprocessableError

try:
    client.search("orders", metadata_filter={"note": {"$contains": "a"}})
except SmriteaUnprocessableError as e:
    print(e.code)  # CONTAINS_NOT_SUPPORTED

Use $eq or $in for exact matches instead.

Related pagesCopy Anchor Link

• Scope memories per user, agent and conversation
• Errors and codes