Metadata Filtering

When a server advertises the filter capability, retrieve (and index/delete) accept a small boolean tree over document metadata. Fields and operators are validated against what the server advertised, so a filter is both expressive and safe.

{ "and": [
    { "field": "lang", "op": "eq", "value": "en" },
    { "or": [
        { "field": "year", "op": "gte", "value": 2023 },
        { "field": "tag",  "op": "in",  "value": ["news", "blog"] } ] } ] }

Structure

A filter node is either a combinator (and / or / not, nesting arbitrarily) or a leaf ({ field, op, value }).

node[]

Boolean combinators over child nodes. An empty and/or array is -32602.

node

Negates a single child node.

string

A metadata field name — MUST be one the server advertised in filter.fields, else -32602.

string

A comparison operator (see below). Must be in the advertised filter.operators, else -32005.

Operators

Operator	`value` shape	Applies to	Meaning
`eq`, `ne`	scalar (string / number / bool)	any	(in)equality
`gt`, `gte`, `lt`, `lte`	number or `date`	`int` / `float` / `date`	ordered comparison
`in`, `nin`	array of scalars	any	set membership / exclusion
`contains`	scalar	`text` (substring) or array-valued field (element membership)	containment
`exists`	boolean	any	field present (`true`) or absent (`false`)

Field types

A server SHOULD advertise filter.fields as a map of field name → type: keyword (exact string), text (tokenised), int, float, bool, date (an RFC 3339 string or epoch-ms), or geo. The allowed operators and the JSON type of value depend on the field type.

A server MUST return -32602 (with error.data.field) when a value’s JSON type is incompatible with the field type, or the field is not advertised. This is also a security boundary: field names are validated precisely because a silently-ignored filter would return wrong — possibly unauthorised — results. Servers MUST parameterise filters into the backing query engine, never string-concatenate. See Security.

Unless a server documents otherwise, string comparison is case-sensitive and byte-ordered.

The canonical builder & validator

Every RCP SDK ships a first-class filter module so you never hand-write the JSON. It has two halves:

A builder — typed leaf constructors (eq ne gt gte lt lte in_ nin contains exists) and combinators (all/any/not_, with & | ~ operator sugar) that make a malformed tree impossible to construct.
A validator — validate(node, fields, operators) that a server runs on the untrusted incoming tree. It returns a normalized tree or a precise -32602 carrying data.field. It enforces field/operator authorization, value-shape (array-vs-scalar), ordered-op-vs-type, combinator/leaf mixing, and a nesting-depth DoS guard.

from rcp import filter as f

# client: build a tree
tree = f.all_(f.eq("lang", "en"), f.gte("year", 2023)) | f.contains("tag", "news")
params = {"query": "...", "filter": tree.to_json()}

# server: validate the untrusted tree against what you advertised
safe = f.validate(
    incoming_filter,
    fields={"lang": "keyword", "year": "int", "tag": "text"},
    operators=["eq", "gte", "contains"],
)  # -> normalized tree, or raises RcpError(-32602, data={"field": ...})

import { filter as f } from "rcp-protocol";

// client
const tree = f.any(
  f.all(f.eq("lang", "en"), f.gte("year", 2023)),
  f.contains("tag", "news"),
);
const params = { query: "...", filter: tree.toJSON() };

// server
const safe = f.validate(incoming, {
  fields: { lang: "keyword", year: "int", tag: "text" },
  operators: ["eq", "gte", "contains"],
}); // -> normalized tree, or throws RcpError(-32602)

use rcp::filter;

// client (& | ! operator sugar via std::ops)
let tree = (filter::eq("lang", "en".into()) & filter::gte("year", 2023.into()))
    | filter::contains("tag", "news".into());
let params = obj(&[("query", "...".into()), ("filter", tree.to_json())]);

// server
let safe = filter::validate(
    Some(&incoming),
    Some(&[("lang", "keyword"), ("year", "int"), ("tag", "text")]),
    Some(&["eq", "gte", "contains"]),
    32, // max nesting depth (DoS guard)
)?; // -> Ok(Some(normalized)) | Ok(None) if empty | Err(RcpError -32602)

#include <rcp/filter.hpp>
using namespace rcp::filter;

// client (&& || ! operator sugar)
auto tree = (eq("lang", "en") && gte("year", 2023)) || contains("tag", "news");
Json params = {{"query", "..."}, {"filter", tree.to_json()}};

// server
auto safe = validate(incoming,
                     /*fields*/ {{"lang", "keyword"}, {"year", "int"}, {"tag", "text"}},
                     /*operators*/ {"eq", "gte", "contains"});
// -> Result<Json>: value is the normalized tree, error is Error{-32602, ...}

Don’t roll your own filter parser. A hand-written server parser turns a malformed tree into a generic -32603 crash; the canonical validate() turns it into a clean, actionable -32602 with data.field — and closes the security boundary above for free. The reference Whoosh adapter (examples/whoosh_adapter.py) calls validate() then compiles the trusted tree into engine queries.

Get Started

Core Concepts

Methods

Features

Operating a Server

Structure

Operators

Field types

The canonical builder & validator

​Structure

​Operators

​Field types

​The canonical builder & validator

Structure

Operators

Field types

The canonical builder & validator