37. Filter and facet an identity on its nested leaf
Date: 2026-11-13
Status
Accepted
Amends ADR 24, section 4.
Context
An inline reference naming an identity stored the ids of its endpoints twice: in each entry, under the field the identity names (contributor.contributor_id for Linked Open Limburg’s contributor), and in a flat companion beside the reference (contributor_id), which plain filters and facets read. The flat copy existed because a nested path was assumed not to be facetable per document.
ADR 36 showed it is. Typesense flattens a leaf under an object[] into one list per document and counts it that way: a work naming one agent in two roles counts once under that agent. A container test pins this against Typesense 30.2.
Decision
An inline reference with an identity filters and facets that identity’s leaf inside each entry. The flat ${name}_id companion is gone.
- The leaf is the identity field’s own filter field. For a plain lookup or an
idOnlyreference that is the field itself (creator.creator); for alocallookup, which stores an object, it is the id leaf beside that object (contributor.contributor_id).physicalFieldsnames it asfilter, which a membership filter reads, and asfacetwhere no facet policy applies. - The identity field must be
filterable. Only an indexed leaf can be filtered or faceted, andfilterableis what indexes it.searchSchemarefuses an identity naming a field without it, rather than indexing the leaf behind the author’s back. A filterable nested field is single-valued, so an identity can no longer name anarrayfield: an entry naming several endpoints is modelled as several entries, one per endpoint. - A facet policy keeps a top-level companion. Typesense cannot exclude ids from a facet at query time, so where the identity’s target declares
facetKeys, the admitted ids are still written to a top-level${name}_facet, as for any facetable reference. - A
locallookup on a Root Type keeps its${name}_idcompanion. That is a different shape: the companion is the only leaf holding the endpoints’ ids, not a second copy of one.
The GraphQL surface does not change: where: { contributor: { in: […] } } and facets { contributor } keep their shape.
Consequences
- Every deployment with an
identityneeds a full reindex. An existing collection lacks the faceted nested leaf, and the in-place rebuild refuses it with the instruction to drop the collection. Of the known deployments, only Linked Open Limburg declares anidentity, and its identity field is alreadyfilterable. - An
identitynaming anarrayfield, previously accepted, is now refused. No known deployment declares one. - A reference with an identity is stored once, and the projection harvests ids only where a facet policy needs them.
- The narrowed companion of an inline reference is renamed from
${name}_id_facetto${name}_facet, since there is no${name}_idfor it to narrow.