Skip to main content

Module extract

obj_core::index

Module extract 

Source
Expand description

Field extraction: Document → encoded index keys.

extract_index_keys is the bridge between a user Document and the per-index B-trees of #57’s catalog layer. For each declared index it walks the document’s field path(s) and hands the resolved Dynamic values to encode_index_key (#55).

§postcard is not self-describing

The M5 Dynamic type ships a from_postcard_bytes decoder that ONLY accepts the tagged-Dynamic wire format — NOT raw native-postcard payloads. M7 field extraction cannot use that decoder for user documents (which are always native postcard).

The workaround is a dedicated serde-driven reflection: a DynamicSerializer walks the document’s serde::Serialize impl and emits a Dynamic tree with Dynamic::Map for every struct and Dynamic::Seq for every sequence. The result is the same shape Dynamic::get is built for, so the top-level field-path walk in extract_index_keys is one Dynamic::get call per IndexSpec::key_paths entry.

§Path limitations

M7 supports top-level field paths only — a single field name within the document’s struct. Dotted paths ("address.city"), array indexing ("tags[0]"), and JSONPath syntax are out of scope. The IndexSpec::key_paths vector is a list of top-level field names; each entry is one Dynamic::get lookup. The limitation is documented in docs/format.md § Indexes.

§Power-of-ten posture

  • Rule 1. No recursion in the extractor itself — the serializer is the only place where the call graph naturally reflects the document structure, and it carries an explicit MAX_REFLECT_DEPTH bound that mirrors MAX_DYNAMIC_DEPTH.
  • Rule 2. Per-key-path iteration is bounded by the spec’s key_paths.len(). Each-kind extraction is bounded by MAX_EACH_ENTRIES (16 384) — beyond which extraction errors with crate::Error::EachIndexTooLarge (added later in #59; M7 currently uses an Error::InvalidArgument placeholder pending that variant’s introduction).
  • Rule 4. extract_index_keys is short — per-kind helpers carry the heavy lifting (one helper per kind).
  • Rule 7. No unwrap / expect on the production path. Missing field / wrong type surface as the specific Error::IndexField* variants.

Constants§

MAX_EACH_ENTRIES
Maximum number of entries a single Each extraction may emit. 16 384 is the same ceiling we use for the per-document key set; exceeding it suggests a runaway data shape rather than a real indexable field.

Functions§

extract_index_keys
Extract the set of encoded index keys for doc under spec.