quickwit-oss/tantivy · error

Facet support in dynamic fields is not yet implemented

Error message

Facet support in dynamic fields is not yet implemented

What it means

index_json_value panics via unimplemented!() when a dynamically-typed JSON leaf is a Facet. Facet values are not yet supported inside dynamic JSON fields and must use a schema-declared facet field. The panic is an explicit not-implemented marker.

Source

Thrown at src/core/json_utils.rs:225

                set_path_id(
                    term_buffer,
                    ctx.path_to_unordered_id
                        .get_or_allocate_unordered_id(json_path_writer.as_str()),
                );
                let val = val.truncate(DATE_TIME_PRECISION_INDEXED);
                term_buffer.append_type_and_fast_value(val);
                postings_writer.subscribe(doc, 0u32, term_buffer, ctx);
            }
            ReferenceValueLeaf::PreTokStr(_) => {
                unimplemented!(
                    "Pre-tokenized string support in dynamic fields is not yet implemented"
                )
            }
            ReferenceValueLeaf::Bytes(_) => {
                unimplemented!("Bytes support in dynamic fields is not yet implemented")
            }
            ReferenceValueLeaf::Facet(_) => {
                unimplemented!("Facet support in dynamic fields is not yet implemented")
            }
            ReferenceValueLeaf::IpAddr(_) => {
                unimplemented!("IP address support in dynamic fields is not yet implemented")
            }
            ReferenceValueLeaf::Custom(_) => {
                unimplemented!("the JSON field does not support custom field types")
            }
        },
        ReferenceValue::Array(elements) => {
            for val in elements {
                index_json_value(
                    doc,
                    val,
                    text_analyzer,
                    term_buffer,
                    json_path_writer,
                    postings_writer,
                    ctx,

View on GitHub (pinned to b5d8deb80c)

Solutions

  1. Declare the field with FacetOptions in the schema and index facets there
  2. Store facet paths as plain strings in the JSON field only if facet aggregation is not needed
  3. Strip facet values from JSON documents before indexing

Example fix

// before
json_obj.insert("category", Value::Facet(facet));
// after
let category = schema_builder.add_facet_field("category", FacetOptions::default());
Defensive patterns

Strategy: validation

Validate before calling

fn json_has_facet(v: &serde_json::Value) -> bool {
    match v {
        serde_json::Value::Array(a) => a.iter().any(json_has_facet),
        serde_json::Value::Object(o) => o.values().any(json_has_facet),
        _ => false,
    }
}
// ensure facets are not inside JSON payloads: assert!(!json_has_facet(&doc_value));

Type guard

fn is_facet_leaf(v: &tantivy::schema::Value) -> bool {
    matches!(v.as_value(), tantivy::schema::ReferenceValueLeaf::Facet(_))
}

Try / catch

let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| index_writer.add_document(doc)));
if result.is_err() { eprintln!("dynamic JSON field contained Facet"); }

Prevention

When it happens

Trigger: Indexing a document where a JSON field's value is a tantivy Facet object via index_document.

Common situations: Mixing facet (hierarchical category) values into JSON documents; bulk-converting legacy documents with facet fields into dynamic JSON fields.

Related errors

AI-assisted analysis of quickwit-oss/tantivy@b5d8deb80c (2026-09-05). Data as JSON: /api/errors/de5cadfadfcfef64. Report an issue: GitHub.