Schema Field Types

Search fields must follow specific types. Types indicate the type of data that is intended to be stored in the field.

Available field types

The currently avaiable field types are text, facet, i64, u64, f64, datetime, bool and json. Any field type may be used for filtering but facet fields differ in that they have a hierarchy and produce facet counts.

Field type configuration options

Every field may be used for either searching or just as display fields within search results. You may also choose not to display a field and only use it for indexing purposes.

text

A text field that may be analyzed and split into tokens before indexing. Used for full text searching or to store display only data that is not indexed.

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
multi	Determines if the field contains a single value or an array of values	false

A facet field. Values are expected to be in the format of “/section/subsection” (multiple levels of depth are optional). Think of this as a taxonomical hierarchy field that can be walked down. Search results will include a count of documents that match the facet.

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
multi	Determines if the field contains a single value or an array of values	false

Note: facet fields are always indexed.

bool

A boolean field. true or false values without quotes.

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
fast	Store the value in a fast field	true
required	Is the field required?	false

i64

A 64 bit signed integer field. Signed integers are used for representing negative numbers. If you aren’t using negative values, use a u64 integer instead. Examples: 3, -1.0, -200, 42

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
fast	Store the value in a fast field	true
required	Is the field required?	false

u64

A 64 bit unsigned integer field. Unsigned integers are used for representing values that contain positive, whole numbers only. Examples: 5, 42

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
fast	Store the value in a fast field	true
required	Is the field required?	false

f64

A 64 bit floating point number field. Floating point numbers are used for representing decimal values. Examples: 3.6, 2.0

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
fast	Store the value in a fast field	true
required	Is the field required?	false

datetime

A 64 bit floating point number field. The datetime type handles dates and datetimes. Since JSON doesn’t have a date type, the datetime field support multiple input types and formats. Values can be in the in the format of integer numbers representing a Unix timestamp or strings containing a rfc3339 formatted date or Unix timestamp. Examples: 2024-07-16T00:25:39Z1, 1736197316

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed	true
fast	Store the value in a fast field	true
required	Is the field required?	false

json

A nested JSON object field. Stores an arbitrary JSON object and lets you query nested keys using dotted paths. For example, given a metadata field containing { "author": "tolkien", "year": 1954 }, you can query metadata.author:tolkien or metadata.year:1954.

Configuration Property	Description	Default value
stored	Whether or not the value is retained in the document store	true
indexed	Determines if the values are indexed (searchable)	true
tokenizer	Tokenizer applied to string values inside the JSON object. `raw` indexes each value verbatim as a single token for exact, case-sensitive matching. `lowercase` indexes each value as a single lowercased token for case-insensitive exact filtering (e.g. `Sony` matches a stored `sony`). `default` is the name of the standard Searchcraft tokenizer (the same one `text` fields use) and performs tokenized, lowercased full-text search. Has no effect on numeric, boolean, or other non-string JSON values. Note: the value `default` names a tokenizer — it is not the default value of this setting. When `tokenizer` is omitted, JSON fields use `raw`.	raw
expand_dots	Treat dots in JSON keys as nested-object path separators. When enabled, a stored key like `"a.b"` is indexed as `{ "a": { "b": ... } }`, so queries do not need to escape the dot.	true
fast	Store values in a fast field (required for sorting/aggregating on JSON values)	true
multi	Determines if the field contains a single object or an array of objects	false
required	Is the field required?	false

Example field declaration:

{
  "metadata": {
    "type": "json",
    "stored": true,
    "indexed": true,
    "tokenizer": "raw",
    "expand_dots": true,
    "fast": true
  }
}

Note: the default value of tokenizer is raw, so JSON string values are matched exactly and are case-sensitive (metadata.brand:Sony matches a stored Sony, but not sony). Set tokenizer to lowercase for case-insensitive exact filtering, or to default for tokenized, case-insensitive full-text matching on JSON string values.

Don’t confuse the two meanings of “default” here: default is the name of the standard Searchcraft full-text tokenizer (the one text fields use by default), whereas the default value of this tokenizer setting is raw. Selecting the default tokenizer for a JSON field is therefore an explicit, opt-in choice.

Fast Fields for Numeric, Datetime and Bool types

Numeric, datetime and bool values can be stored in a fast scoring field which is a column-oriented storage used for range queries and aggregations. For those familiar with Lucene, this is similar to DocValues. There is a trade-off of speed vs. accuracy when using fast scoring fields.

If you want to be able to order by a field it must be configured as a fast field.

For number fields you typically always want fast enabled unless you know what this does. The fast attribute is not used on text fields or facet fields.

Fast fields are not recommended for multi-value fields as only the last value is retained

Additional Types

Additional types are planned to be supported in the future such as geospatial. Additional format options for datetime are also planned to be supported.