@spec all() :: {:ok, t()}

Creates a query that matches all documents.

Examples

iex> query = TantivyEx.Query.all()
iex> is_reference(query)
true

@spec boolean([t()], [t()], [t()]) :: {:ok, t()} | {:error, String.t()}

Creates a boolean query combining multiple queries with AND, OR, NOT logic.

Boolean queries allow complex combinations of other queries:

• must_queries: All queries in this list must match (AND)
• should_queries: At least one query in this list should match (OR)
• must_not_queries: No queries in this list should match (NOT)

Parameters

• must_queries: List of queries that must all match
• should_queries: List of queries where at least one should match
• must_not_queries: List of queries that must not match

Examples

iex> {:ok, term1} = TantivyEx.Query.term(schema, "title", "hello")
iex> {:ok, term2} = TantivyEx.Query.term(schema, "body", "world")
iex> {:ok, term3} = TantivyEx.Query.term(schema, "category", "spam")
iex> {:ok, query} = TantivyEx.Query.boolean([term1], [term2], [term3])

@spec empty() :: {:ok, t()}

Creates a query that matches no documents.

Examples

iex> {:ok, query} = TantivyEx.Query.empty()
iex> is_reference(query)
true

@spec exists(TantivyEx.Schema.t(), String.t()) :: {:ok, t()} | {:error, String.t()}

Creates an exists query to check if a field has any value.

Exists queries match documents where the specified field contains any value.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to check

Examples

iex> {:ok, query} = TantivyEx.Query.exists(schema, "email")

@spec facet_term(TantivyEx.Schema.t(), String.t(), String.t()) ::
  {:ok, t()} | {:error, String.t()}

Creates a facet term query for exact facet matching.

Facet queries are optimized for filtering documents by facet values. This is the preferred way to query facet fields.

Parameters

• schema: The index schema containing the facet field definition
• field_name: The name of the facet field
• facet_value: The exact facet value to match

Examples

iex> {:ok, query} = TantivyEx.Query.facet_term(schema, "categories", "electronics")
iex> is_reference(query)
true

@spec fuzzy(
  TantivyEx.Schema.t(),
  String.t(),
  String.t(),
  non_neg_integer(),
  boolean()
) ::
  {:ok, t()} | {:error, String.t()}

Creates a fuzzy query for approximate matching.

Fuzzy queries match terms that are similar to the specified term, allowing for typos and minor spelling differences.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• term_value: The term to match approximately
• distance: Maximum edit distance (default: 2)
• prefix: Whether to require exact prefix match (default: true)

Examples

iex> {:ok, query} = TantivyEx.Query.fuzzy(schema, "title", "hello", 2, true)
iex> is_reference(query)
true

@spec more_like_this(TantivyEx.Schema.t(), map() | String.t(), keyword()) ::
  {:ok, t()} | {:error, String.t()}

Creates a more-like-this query for similarity search.

More-like-this queries find documents similar to a given document or text.

Parameters

• schema: The schema containing field definitions
• document: The document as JSON string to find similar documents to
• options: Keyword list of options including:
  • min_doc_frequency: Minimum document frequency for terms (default: 5)
  • max_doc_frequency: Maximum document frequency for terms (default: unlimited)
  • min_term_frequency: Minimum term frequency in document (default: 2)
  • max_query_terms: Maximum number of query terms (default: 25)
  • min_word_length: Minimum word length (default: 0)
  • max_word_length: Maximum word length (default: unlimited)
  • boost_factor: Boost factor for scoring (default: 1.0)

Examples

iex> doc = Jason.encode!(%{"title" => "Machine Learning", "body" => "AI and algorithms"})
iex> {:ok, query} = TantivyEx.Query.more_like_this(schema, doc, min_doc_frequency: 2, max_query_terms: 10)

@spec parse(parser(), String.t()) :: {:ok, t()} | {:error, String.t()}

Parses a query string using the given parser.

Supports Lucene-style query syntax including:

• Field-specific queries: title:hello
• Phrase queries: title:"hello world"
• Range queries: price:[100 TO 500]
• Boolean operators: title:hello AND body:world
• Wildcards: title:hel*
• Fuzzy queries: title:hello~2

Parameters

• parser: The query parser
• query_str: The query string to parse

Examples

iex> {:ok, query} = TantivyEx.Query.parse(parser, "title:hello AND body:world")
iex> is_reference(query)
true

@spec parser(TantivyEx.Index.t(), [String.t()]) ::
  {:ok, parser()} | {:error, String.t()}

Creates a new query parser for the given index and default fields.

The query parser allows parsing Lucene-style query strings.

Parameters

• index: The index to use for field resolution
• default_fields: List of field names to search by default

Examples

iex> {:ok, parser} = TantivyEx.Query.parser(index, ["title", "body"])
iex> is_reference(parser)
true

@spec phrase(TantivyEx.Schema.t(), String.t(), [String.t()]) ::
  {:ok, t()} | {:error, String.t()}

Creates a phrase query for exact phrase matching.

Phrase queries match documents where the specified field contains the exact sequence of terms.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• phrase_terms: List of terms that must appear in order

Examples

iex> {:ok, query} = TantivyEx.Query.phrase(schema, "title", ["hello", "world"])
iex> is_reference(query)
true

@spec phrase_prefix(TantivyEx.Schema.t(), String.t(), [String.t()], pos_integer()) ::
  {:ok, t()} | {:error, String.t()}

Creates a phrase prefix query for autocomplete-style search.

Phrase prefix queries match phrases where the last term is treated as a prefix. Useful for autocomplete functionality.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• phrase_terms: List of terms, where the last one is treated as a prefix
• max_expansions: Maximum number of terms to expand the prefix to (default: 50)

Examples

iex> {:ok, query} = TantivyEx.Query.phrase_prefix(schema, "title", ["hello", "wor"], 50)

@spec range_f64(TantivyEx.Schema.t(), String.t(), float() | nil, float() | nil) ::
  {:ok, t()} | {:error, String.t()}

Creates a range query for f64 fields.

Parameters

• schema: The schema containing the field
• field_name: The name of the numeric field
• start_value: The start of the range (nil for unbounded)
• end_value: The end of the range (nil for unbounded)

@spec range_i64(TantivyEx.Schema.t(), String.t(), integer() | nil, integer() | nil) ::
  {:ok, t()} | {:error, String.t()}

Creates a range query for i64 fields.

Parameters

• schema: The schema containing the field
• field_name: The name of the numeric field
• start_value: The start of the range (nil for unbounded)
• end_value: The end of the range (nil for unbounded)

@spec range_u64(
  TantivyEx.Schema.t(),
  String.t(),
  non_neg_integer() | nil,
  non_neg_integer() | nil
) ::
  {:ok, t()} | {:error, String.t()}

Creates a range query for u64 fields.

Range queries match documents where the field value falls within the specified range.

Parameters

• schema: The schema containing the field
• field_name: The name of the numeric field
• start_value: The start of the range (nil for unbounded)
• end_value: The end of the range (nil for unbounded)

Examples

iex> {:ok, query} = TantivyEx.Query.range_u64(schema, "price", 100, 500)
iex> {:ok, query} = TantivyEx.Query.range_u64(schema, "price", 100, nil)  # >= 100
iex> {:ok, query} = TantivyEx.Query.range_u64(schema, "price", nil, 500)  # <= 500

@spec regex(TantivyEx.Schema.t(), String.t(), String.t()) ::
  {:ok, t()} | {:error, String.t()}

Creates a regex query for advanced pattern matching.

Regex queries allow full regular expression matching against field values.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• pattern: The regular expression pattern

Examples

iex> {:ok, query} = TantivyEx.Query.regex(schema, "title", "h[ae]llo")
iex> {:ok, query} = TantivyEx.Query.regex(schema, "email", ".*@example\.com")

@spec term(TantivyEx.Schema.t(), String.t(), any()) ::
  {:ok, t()} | {:error, String.t()}

Creates a term query for exact matching.

Term queries match documents where the specified field contains the exact term.

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• term_value: The exact term to match

Examples

iex> {:ok, query} = TantivyEx.Query.term(schema, "title", "hello")
iex> is_reference(query)
true

@spec wildcard(TantivyEx.Schema.t(), String.t(), String.t()) ::
  {:ok, t()} | {:error, String.t()}

Creates a wildcard query for pattern matching.

Wildcard queries support * (matches any sequence of characters) and ? (matches any single character).

Parameters

• schema: The schema containing the field
• field_name: The name of the field to search
• pattern: The wildcard pattern

Examples

iex> {:ok, query} = TantivyEx.Query.wildcard(schema, "title", "hel*")
iex> {:ok, query} = TantivyEx.Query.wildcard(schema, "title", "h?llo")