[Feature Request] Optionally include field types in facet_counts responses

Aperta
  • Qualcosa non va?
#3,030 0 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
cpp
Ambito
backend-api-design, search

Direzione di ricerca

Inizia dalla costruzione della risposta delle facet in src/collection.cpp intorno alle righe 5440-5480, quindi confronta lo schema delle facet in openapi.yml intorno alle righe 3895-3920. Traccia il modo in cui le richieste normali e multi_search risolvono i campi facet, incluse le facet dinamiche, unite e di intervallo. Il lavoro è completato quando la risposta opt-in include il tipo di campo completo risolto, mentre le risposte predefinite e counts[].value rimangono invariati.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

feature-request

Describe your feature request

Add an opt-in search parameter that includes each facet field's Typesense schema type in the corresponding facet_counts entry.

For example, a search request could specify:

{
  "q": "*",
  "query_by": "name",
  "facet_by": "free_shipping",
  "include_facet_field_types": true
}

The response would then include field_type:

{
  "field_name": "free_shipping",
  "field_type": "bool",
  "counts": [
    {
      "value": "true",
      "count": 1678
    }
  ]
}

The exact parameter name is only a suggestion. The important behavior is:

  • The parameter is disabled by default.
  • When omitted or set to false, the existing response remains unchanged.
  • When enabled, each facet_counts entry includes the resolved Typesense schema type as field_type.
  • The type should preserve the complete Typesense type, including array information, for example bool, int32, int64, float, string, bool[], or int32[].
  • For fields created through auto or dynamic schema detection, the resolved concrete type should be returned rather than auto.
  • This should work consistently for regular searches and multi_search.
  • The existing value property should remain a string for backward compatibility.

This proposal does not require returning the complete collection schema. It only adds the type associated with each requested facet field.

Please describe your use-case for the feature request

Typesense currently serializes all facet values as strings, regardless of their schema type. For example, the following facet values are indistinguishable from the response alone:

  • The boolean value true and the string value "true".
  • The integer value 123 and the string value "123".
  • A scalar field and an array field containing the same value.

A client that dynamically builds filters from facet_counts therefore needs access to the collection schema to interpret each facet correctly and construct the appropriate filter expression.

The main motivation for this feature is to avoid requiring clients to separately load, cache and maintain the collection schema.

The current alternatives introduce several problems:

  1. Additional requests

    The client must call GET /collections/:collection before it can safely interpret facet values. This adds another request per collection or application lifecycle.

  2. Schema state management

    The client must cache the schema, decide when to refresh it and maintain a mapping between every facet field and its type.

  3. Race conditions

    A cached or locally bundled schema can become stale after a schema update, dynamic field addition, reindex or collection-alias switch. A search response can then contain facets from the new schema while the client still interprets them using the old schema.

    This can cause the client to construct an incorrect filter or parse a facet value using the wrong type. Coordinating schema changes with all deployed clients is especially difficult in browser and mobile applications.

  4. Additional permissions

    A typical browser search key only needs documents:search. Retrieving the schema requires also granting collections:get, even though the client only needs the types of the facet fields present in the search response.

  5. Dynamic clients

    Generic search clients, dashboards and UI component libraries may not know the collection schema at build time. Returning the type together with each facet would make the facet response self-describing without sending the complete schema.

Including field_type in the same response would guarantee that the type metadata and facet data come from the same search execution and schema state, eliminating this class of synchronization race conditions.

Because multi-search requests can return many facet groups, the feature should be opt-in. Clients that do not need type information would retain the current response size and behavior.

Describe alternatives you've considered

  1. Fetch and cache the collection schema

    This works, but requires an additional request, additional API-key permissions, cache invalidation and synchronization with schema or alias changes.

  2. Bundle or hard-code the schema in the client

    This duplicates server-side schema state and requires coordinated deployments. It is vulnerable to race conditions when the server schema changes before all clients have been updated.

  3. Infer the type from the facet value

    This is not reliable because all facet values are strings. "true" could be either a boolean or a string, and "123" could be an integer, float or string. It is also impossible to determine whether the underlying field is a scalar or an array.

  4. Infer numeric fields from stats

    This does not cover boolean, string or array distinctions and makes clients dependent on incidental response properties rather than explicit schema metadata.

  5. Return facet values using native JSON types

    Changing value from a string to a boolean or number would be a breaking response-contract change. Adding an opt-in field_type property preserves the existing representation and client compatibility.

Additional context

Typesense already looks up the facet field in the search schema and converts integer, float and boolean facet values to strings when constructing the response:

https://github.com/typesense/typesense/blob/a7c94ee99ac1e06880adea62e8bb00b812f85842/src/collection.cpp#L5440-L5480

The current API specification defines counts[].value as a string and does not expose the underlying field type:

https://github.com/typesense/typesense-api-spec/blob/cbdcaf9f3f6b94cfcaa15d53310f7bbbbb4b5cb2/openapi.yml#L3895-L3920

Related issues demonstrate the current string representation but do not request type metadata:

For joined or referenced facets, field_type should ideally represent the type of the resolved facet field in the referenced collection. For numerical range facets, it should represent the underlying numerical field type even though the returned range labels remain strings.

Lingua principale
C++
Stelle
27.1k
Fork
1k
Merge medio
4g 4h
PR unite (30g)
15

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di typesense/typesense

Tutte le issue di typesense/typesense

Issue simili

Altre issue su C++

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.