Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -71,5 +71,5 @@ An inline reference on a Root Type may list leaves of its Reference Type in
- A derived judgement over entries, such as LOL’s `hasMedia` (“some
reproduction has a thumbnail”), stays a `derive`. Typesense has no native
presence filter, so a generic one would be the same index-time boolean.
(Superseded 2026-11-16 for a Root Type’s own field: [ADR 38](0038-filter-and-facet-a-field-on-whether-it-has-a-value.md)
(Superseded 2026-11-16 for a Root Type’s own field: [ADR 40](0040-filter-and-facet-a-field-on-whether-it-has-a-value.md)
writes that boolean once, in LDE.)
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 38. Filter and facet a field on whether it has a value
# 40. Filter and facet a field on whether it has a value

Date: 2026-11-16

Expand All @@ -8,7 +8,8 @@ Accepted

Supersedes the last consequence of
[ADR 36](0036-facet-a-root-document-on-its-entries-leaves.md) for a Root
Type’s own field.
Type’s own field. Extended to an inline entry’s leaf by
[ADR 41](0041-filter-and-facet-a-root-document-on-whether-an-entrys-leaf-has-a-value.md).

## Context

Expand Down Expand Up @@ -78,7 +79,8 @@ count } } }`, as `‹Type›‹Field›Facets`, the per-field grouping ADR 36 ga
refuses it on:
- a field of a Reference Type and an inline reference: presence on an
entry’s leaf, counted per root document as ADR 36’s faceted leaves are,
is [#1091](https://github.com/ldelements/lde/issues/1091)’s second part;
is [#1091](https://github.com/ldelements/lde/issues/1091)’s second part
(done since in ADR 41, declared on the reference);
- a field that is already `facetable`: its facet would have to become an
object to hold both kinds of bucket, the shape change
[#1090](https://github.com/ldelements/lde/issues/1090) makes once for
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# 41. Filter and facet a root document on whether an entry’s leaf has a value

Date: 2026-11-16

## Status

Accepted

Extends [ADR 40](0040-filter-and-facet-a-field-on-whether-it-has-a-value.md)
to a leaf of an inline reference.

## Context

ADR 40 lets a Root Type’s own field declare presence and refuses it on an
inline reference and on a Reference Type’s field. Linked Open Limburg still
derives `hasMedia`, “an `associatedMedia` entry has a `thumbnailUrl`”, beside
the reference it describes.

A boolean inside each entry does not answer that question. Typesense flattens
a leaf under an `object[]` into one list per document
([ADR 36](0036-facet-a-root-document-on-its-entries-leaves.md)), so a work
with one entry that has a thumbnail and one that lacks it would count in both
buckets, and a work with no entries in neither.

## Decision

An inline reference on a Root Type may list leaves of its Reference Type in
`ref.presenceLeaves`. For each, the root document is filtered and faceted on
whether any entry holds a value for the leaf.

- **One boolean per root document.** The projection writes
`${reference}_${leaf}_exists`, true when any entry holds a value for the
leaf in ADR 40’s sense and false otherwise, a document with no entries
included. It reads the entries before pruning, so a leaf with no Role of its
own still counts. `physicalFields(reference).leafExists` names it, and the reserved-name
check covers it.
- **Declared on the reference**, as ADR 36 declares faceted leaves: the count
is a fact about the root, and a Reference Type nested from several places
may be counted from one and not another.
- **A weld of one condition selects it.**
`{ field: 'associatedMedia', entry: [{ field: 'thumbnailUrl', exists: true }] }`
compiles to the root’s boolean. `exists` welded to other conditions is
refused (`exists-in-weld`): a root-level boolean cannot hold of the same
entry as another condition. Through a join it stays refused, as in ADR 40.
- **The facet is `‹reference›.‹leaf›.exists`**, on the axis of the same name.
It owns the one-condition weld on `exists`, never a weld on the leaf’s value,
and a faceted leaf’s facet never owns it.
- **GraphQL nests it under the leaf.** The leaf’s key in `‹Edge›Where` takes
`exists`, typed as an own field’s is (`ExistsFilter`, `‹Filter›OrExists`).
Setting it beside another key of the same weld is an error naming the
rewrite. The facet is served as `facets { associatedMedia { thumbnailUrl {
exists } } }`, inside the reference’s facet object.
- **One set of leaves per Reference Type.** `‹Edge›Where` is shared by every
reference nesting that type, and its keys follow the presence leaves. So
`searchSchema` requires every reference nesting one type to declare the same
leaves, rather than emit a filter input per reference. Through a join, a
reference with presence leaves takes `‹Edge›JoinedFilter`, without `exists`.

## Consequences

- LOL drops its derived `hasMedia`, as it drops `hasCoordinates` once
[#1090](https://github.com/ldelements/lde/issues/1090) lands.
- The reference must be `filterable`, since a bucket is selected through a
condition on one entry. A leaf is held to what an own field is: neither
`text` nor `boolean`. A leaf that is itself an inline reference is refused,
since an entry’s entries are not counted.
- Until [#1090](https://github.com/ldelements/lde/issues/1090) gives each
field one facet object, a leaf cannot be both a faceted leaf and a presence
leaf of one reference, and a `facetable` reference cannot declare presence
leaves: both facets would claim one GraphQL key.
- A lookup reference may not declare presence leaves until #1090 brings a
target’s values onto the root document.
- Two `filterable` references on Root Types nesting one Reference Type with
different leaves are refused, until #1090’s per-reference filter inputs. A
deployment that needs both before then declares a second Reference Type.
18 changes: 17 additions & 1 deletion docs/reference/search-api-graphql.md
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,18 @@ role: { in: ["etser"] } } }` asks for _this person in this role_, where the
without the keys of fields declaring presence alone. A type declaring none
keeps one `‹Type›Where` for both.

An inline reference’s
[presence leaves](./search#presence-on-an-entry-s-leaf) take `exists` in its
reference type’s `‹Edge›Where`, typed as a field of the root’s own is
(`ExistsFilter`, or `‹Filter›OrExists` for a `filterable` leaf):
`where: { associatedMedia: { where: { thumbnailUrl: { exists: true } } } }`.
Whether any entry holds a value is recorded per document, so `exists` is
welded to nothing else: setting it beside another key of the same
`‹Edge›Where` is an error naming the rewrite into two conditions. Every
reference nesting one reference type declares the same presence leaves, so
`‹Edge›Where` stays shared; through a join, where no companion is read, a
reference with presence leaves takes `‹Edge›JoinedFilter`, without `exists`.

- **`orderBy`**: `RELEVANCE` plus every `sortable` field, as an enum – field
names SCREAMING_SNAKE_CASEd (`datePosted` → `DATE_POSTED`); `direction`
defaults to `DESC`.
Expand Down Expand Up @@ -343,7 +355,11 @@ license { buckets { value count } } } }`, typed `‹Type›‹Reference›Facets
dateCreated { exists { value count } } }`, typed `‹Type›‹Field›Facets`
(`WorkDateCreatedFacets`) with `exists: [BooleanBucket!]!`. The object
leaves room for a field’s value buckets beside it, once a field may be both
`facetable` and declare presence.
`facetable` and declare presence. A presence leaf’s facet sits under the
reference, one level further down: `facets { associatedMedia { thumbnailUrl {
exists { value count } } } }`, typed `‹Type›‹Reference›‹Leaf›Facets`
(`WorkAssociatedMediaThumbnailUrlFacets`), beside the reference’s faceted
leaves.

Selecting facet fields IS
the request, and the whole selection is **batched per request**: one
Expand Down
6 changes: 5 additions & 1 deletion docs/reference/search-typesense.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,11 @@ value, so `exists` compiles to `${name}_exists:=true` or `:=false`, and the
facet `‹field›.exists` counts the companion. The projection writes it on every
document, `false` included, so the companion is not optional. A field
declaring presence alone is internal, so the companion is all the collection
declares for it.
declares for it. An inline reference’s
[presence leaves](./search#presence-on-an-entry-s-leaf) each get a top-level
`${reference}_${leaf}_exists` of the same kind, true when any entry holds a
value: an `exists` welded alone to an entry compiles to it, never to a
condition inside the nested object.

An `InPlaceRebuild` additionally refuses a type whose declared
[dataset field](#provenance) inherits a policy: it enumerates the indexed
Expand Down
58 changes: 55 additions & 3 deletions docs/reference/search.md
Original file line number Diff line number Diff line change
Expand Up @@ -1258,12 +1258,64 @@ declaring no presence (`no-presence`), which is also what a weld meets.
`validateSearchType` accepts `presence` on a Root Type’s own field only, and
`searchSchema` says why in full. It refuses
it on a field of a Reference Type and on an inline reference, whose entries
hold no companion yet ([#1091](https://github.com/ldelements/lde/issues/1091));
on a `text` field, which stores its values per language; on a `boolean`, which
are counted through the reference’s
[presence leaves](#presence-on-an-entry-s-leaf) instead; on a `text` field, which stores its values per language; on a `boolean`, which
states its own absence as `false`; and on a field that is already `facetable`,
since its facet would have to become an object to hold both kinds of bucket
([#1090](https://github.com/ldelements/lde/issues/1090))
([ADR 38](../decisions/0038-filter-and-facet-a-field-on-whether-it-has-a-value.md)).
([ADR 40](../decisions/0040-filter-and-facet-a-field-on-whether-it-has-a-value.md)).

### Presence on an entry’s leaf

A root document can be filtered and faceted on whether **any entry** of an
inline reference holds a value for a leaf – “a work with a reproduction that
has a thumbnail”. List the leaves in `ref.presenceLeaves`, beside
[`facetedLeaves`](#faceting-on-an-entry-s-leaf):

```ts
{
name: 'associatedMedia',
kind: 'reference',
array: true,
output: true,
filterable: true,
ref: {
strategy: 'inline',
typeName: 'MediaObject',
presenceLeaves: ['thumbnailUrl'],
},
}
```

The projection writes one boolean per root document,
`associatedMedia_thumbnailUrl_exists` (`physicalFields(field).leafExists`): `true` when
any entry holds a value for the leaf, in the sense above, and `false`
otherwise – a document with no entries included. It is read before pruning, so
a leaf declaring no role of its own still counts. A boolean inside each entry
would not answer the question: an engine flattens it into one list per
document, so a work with one entry that has a thumbnail and one that lacks it
would count in both buckets.

The facet is `associatedMedia.thumbnailUrl.exists`, and a bucket is selected
by `exists` welded to one entry alone:
`{ field: 'associatedMedia', entry: [{ field: 'thumbnailUrl', exists: true }] }`
(GraphQL: `where: { associatedMedia: { where: { thumbnailUrl: { exists: true } } } }`).
That weld is the facet’s own clause; a condition on the leaf’s value is not,
nor is `exists` the selection of a facet on the leaf’s values. `exists`
welded to other conditions is refused (`exists-in-weld`): whether any entry
holds a value is recorded per document, so it cannot hold of the same entry
as another condition. Through a join it is refused like any `exists`
(`joined-presence`).

The reference is `filterable`, sits on a Root Type and – for now – is not
`facetable` itself; each leaf is declared by the reference type, named once,
and neither `text`, `boolean`, an inline reference nor – for now – one of the
reference’s faceted leaves. Every `filterable` inline reference on a Root
Type nesting the same reference type declares the same presence leaves,
because they share the type’s filter input. The two “for now” refusals and the
shared leaves are lifted by per-field facet objects and per-reference filter
inputs ([#1090](https://github.com/ldelements/lde/issues/1090))
([ADR 41](../decisions/0041-filter-and-facet-a-root-document-on-whether-an-entrys-leaf-has-a-value.md)).

### Facet policy

Expand Down
Loading
Loading