Skip to content

feat(search)!: filter and facet a root document on whether a referent’s leaf has a value - #1101

Merged
ddeboer merged 1 commit into
mainfrom
feat/search-lookup-presence
Nov 17, 2026
Merged

ddeboer merged 1 commit into
mainfrom
feat/search-lookup-presence

Conversation

@ddeboer

@ddeboer ddeboer commented Nov 17, 2026

Copy link
Copy Markdown
Member

Fix #1090, following the revised design.

A lookup naming one target may declare presenceLeaves, so a root document is filtered and faceted on whether a referent holds a value for that leaf:

creativeWorks(where: { contentLocation: { where: { latitude: { exists: true } } } }) {
  facets {
    contentLocation(limit: 20) {
      buckets { value count }
      totalValues
      latitude { exists { value count } }
    }
  }
}
  • Index time, no pass after all datasets. The extraction reads each leaf one hop from the root, and the target type’s transforms run on the referents in the batch (ADR 39’s mechanism). A referent named by IRI alone is seeded as <referent> rdf:type <class> so its type’s transforms can describe it from its key; a lookup into its own type seeds through that type’s own transforms. The projection writes one boolean per root document, ${reference}_${leaf}_exists, counting only referents with an IRI – the ids the lookup stores.
  • Query. { field, leaf, exists } is a plain criterion on the root; each key of a lookup’s GraphQL where is one, ANDed like sibling keys.
  • One facet object per field. Everything counted on a field is served in one object: its own buckets/totalValues (capped by the field’s limit), exists, and one sub-object per leaf, each part charged as a facet calculation. A field counting only its own values keeps IRIFacet/ValueFacet. This lifts four refusals: presence on a facetable field (feat(search)!: filter and facet a field on whether it has a value #1095), leaves on a facetable reference (feat(search): facet a root document on its entries’ leaves #1049), a leaf counted by value and by presence, and one set of presence leaves per reference type (feat(search)!: filter and facet a root document on whether an entry’s leaf has a value #1099).
  • Filters. A reference counting leaves takes a per-reference ‹Type›‹Field›Filter/‹Type›‹Field›Where. Adding leaves to a reference therefore changes its filter type.
  • Refused for now: several targets, a joinable lookup, a lookup reading literals as periods, an idOnly reference, a leaf without a path, and leaves named buckets, totalValues or exists. Faceting a lookup’s leaf by value stays out.

ADR 42 records the decision.

Open points, for later: inline presence leaves still use a weld of one exists while a lookup’s use the plain leaf criterion; the combined facet object charges buckets and totalValues separately, so it costs more than a plain IRIFacet for the same pair.

BREAKING CHANGE: GraphQL facet objects are renamed and reshaped. ‹Type›‹Reference›Facets and ‹Type›‹Field›Facets become ‹Type›‹Field›Facet, and a presence leaf’s ‹…›‹Leaf›Facets becomes ‹Type›‹Field›‹Leaf›Facet. A field whose facet also counts its presence or a leaf is served as ‹Type›‹Field›Facet { buckets totalValues exists ‹leaf› } instead of IRIFacet or ValueFacet. A reference counting faceted or presence leaves takes ‹Type›‹Field›Filter (with ‹Type›‹Field›Where) instead of ‹Edge›Filter or ‹Target›Filter, and ‹Edge›JoinedFilter becomes ‹Type›‹Field›JoinedFilter; variables typed with the old names stop validating. In @lde/search, PhysicalFields.leafExists covers a lookup’s presence leaves, PresenceCriterion takes an optional leaf, and the SearchTypeIssue reasons presence-with-facetable, presence-leaves-not-inline, presence-leaves-with-facetable and presence-leaf-faceted are replaced by presence-leaves-on-id-only, presence-leaves-with-several-targets, presence-leaves-with-joinable, presence-leaves-with-literal, presence-leaf-reserved-name and presence-leaf-without-path. A target type’s transform also receives referents seeded as <referent> rdf:type <class>.


…’s leaf has a value

A lookup naming one target may declare presenceLeaves: the extraction reads each leaf one hop
from the root, the target type’s transforms run on the referents in the batch – a referent named
by IRI alone seeded with its type, through the type’s own transforms for a lookup into its own
type – and the projection writes one boolean per root document, counting referents with an IRI
only. A plain criterion on the root, { field, leaf, exists }, selects it, and each key of the
lookup’s GraphQL where is one such criterion, ANDed like sibling keys. Everything counted on one
field is served in one facet object, each part charged as a facet calculation, which lifts the
refusals of presence on a facetable field, leaves on a facetable reference, a leaf counted by
value and by presence, and one set of presence leaves per reference type.

BREAKING CHANGE: GraphQL facet objects are renamed and reshaped. The
‹Type›‹Reference›Facets and ‹Type›‹Field›Facets objects become
‹Type›‹Field›Facet, and a presence leaf’s ‹…›‹Leaf›Facets becomes
‹Type›‹Field›‹Leaf›Facet. A field whose facet also counts its presence or a
leaf is served as ‹Type›‹Field›Facet { buckets totalValues exists ‹leaf› }
instead of IRIFacet or ValueFacet; select its buckets as
facetField(limit) { buckets { … } }. A reference counting faceted or presence
leaves takes ‹Type›‹Field›Filter, with ‹Type›‹Field›Where, instead of
‹Edge›Filter or ‹Target›Filter, and ‹Edge›JoinedFilter becomes
‹Type›‹Field›JoinedFilter; variables typed with the old names stop
validating, and adding leaves to a reference later changes its filter type
the same way. In @lde/search, PhysicalFields.leafExists covers a lookup’s
presence leaves too, PresenceCriterion takes an optional leaf, and the
SearchTypeIssue reasons presence-with-facetable, presence-leaves-not-inline,
presence-leaves-with-facetable and presence-leaf-faceted are gone, replaced
by presence-leaves-on-id-only, presence-leaves-with-several-targets,
presence-leaves-with-joinable, presence-leaves-with-literal,
presence-leaf-reserved-name and presence-leaf-without-path. A target type’s
transform also receives referents seeded as <referent> rdf:type <class>.
@ddeboer
ddeboer merged commit 98b4e43 into main Nov 17, 2026
4 checks passed
@ddeboer
ddeboer deleted the feat/search-lookup-presence branch November 17, 2026 11:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Facet a root document on a leaf of the documents its lookup references

1 participant