TantivyEx.Facet (TantivyEx v0.4.1)

View Source

Faceted search functionality for TantivyEx.

Facets are hierarchical categories that allow for sophisticated navigation and filtering of search results. This module provides comprehensive faceted search capabilities including facet collection, drilling down, and hierarchical navigation.

Examples

# Basic facet collection
{:ok, facet_collector} = TantivyEx.Facet.collector_for_field("category")
:ok = TantivyEx.Facet.add_facet(facet_collector, "/electronics")
{:ok, facet_counts} = TantivyEx.Facet.search(searcher, query, facet_collector)

# Get top facets
top_facets = TantivyEx.Facet.get_top_k(facet_counts, "/electronics", 10)

# Hierarchical facet navigation
child_facets = TantivyEx.Facet.get_children(facet_counts, "/electronics/computers")

# Facet filtering with boolean queries
facet_query = TantivyEx.Facet.facet_term_query("category", "/electronics/laptops")
{:ok, filtered_results} = TantivyEx.Searcher.search(searcher, facet_query, 100, true)

Facet Structure

Facets are hierarchical paths separated by forward slashes:

  • /electronics - Top level category
  • /electronics/computers - Subcategory
  • /electronics/computers/laptops - Sub-subcategory

Each level can be searched and counted independently, allowing for drill-down navigation.

Summary

Functions

add_facet(collector_ref, facet_path)

Adds a facet path to the collector for counting.

collector_for_field(field_name)

Creates a new facet collector for the specified field.

facet_term_query(schema, field_name, facet_path)

Creates a term query for filtering by a specific facet.

from_text(facet_path)

Creates a facet from a text path.

get_children(facet_counts, parent_path)

Gets all child facets for a given parent facet path.

get_count(facet_counts, facet_path)

Gets the total count for a specific facet path.

get_top_k(facet_counts, facet_path, k)

Gets the top K facets for a given facet path.

multi_facet_query(field_name, facet_paths, occur)

Creates a multi-facet boolean query for filtering by multiple facets.

search(searcher_ref, query_ref, collector_ref)

Performs a search with facet collection.

to_string(facet_ref)

Gets the string representation of a facet.

Functions

add_facet(collector_ref, facet_path)

@spec add_facet(reference(), String.t()) :: :ok | {:error, String.t()}

Adds a facet path to the collector for counting.

Parameters

  • collector_ref - Reference to the facet collector
  • facet_path - The hierarchical facet path (e.g., "/electronics/computers")

Returns

  • :ok on success
  • {:error, reason} on failure

Example

:ok = TantivyEx.Facet.add_facet(collector, "/electronics")
:ok = TantivyEx.Facet.add_facet(collector, "/electronics/computers")

collector_for_field(field_name)

@spec collector_for_field(String.t()) :: {:ok, reference()} | {:error, String.t()}

Creates a new facet collector for the specified field.

Parameters

  • field_name - The name of the facet field to collect on

Returns

  • {:ok, collector_ref} on success
  • {:error, reason} on failure

Example

{:ok, collector} = TantivyEx.Facet.collector_for_field("category")

facet_term_query(schema, field_name, facet_path)

@spec facet_term_query(reference(), String.t(), String.t()) ::
  {:ok, reference()} | {:error, String.t()}

Creates a term query for filtering by a specific facet.

Parameters

  • schema - The index schema containing the facet field definition
  • field_name - The facet field name
  • facet_path - The facet path to filter by

Returns

  • {:ok, query_ref} on success
  • {:error, reason} on failure

Example

{:ok, facet_query} = TantivyEx.Facet.facet_term_query(schema, "category", "/electronics/laptops")
{:ok, results} = TantivyEx.Searcher.search(searcher, facet_query, 100, true)

from_text(facet_path)

@spec from_text(String.t()) :: {:ok, reference()} | {:error, String.t()}

Creates a facet from a text path.

Parameters

  • facet_path - The facet path string

Returns

  • {:ok, facet_ref} on success
  • {:error, reason} on failure

Example

{:ok, facet} = TantivyEx.Facet.from_text("/electronics/laptops")

get_children(facet_counts, parent_path)

@spec get_children(map(), String.t()) :: [{String.t(), non_neg_integer()}]

Gets all child facets for a given parent facet path.

Parameters

  • facet_counts - The facet counts result from search/3
  • parent_path - The parent facet path

Returns

  • List of tuples {facet_path, count} for all children

Example

children = TantivyEx.Facet.get_children(facet_counts, "/electronics")
# Returns: [{"/electronics/computers", 150}, {"/electronics/phones", 89}, ...]

get_count(facet_counts, facet_path)

@spec get_count(map(), String.t()) :: non_neg_integer()

Gets the total count for a specific facet path.

Parameters

  • facet_counts - The facet counts result from search/3
  • facet_path - The facet path to get count for

Returns

  • The count as integer, or 0 if not found

Example

count = TantivyEx.Facet.get_count(facet_counts, "/electronics/laptops")

get_top_k(facet_counts, facet_path, k)

@spec get_top_k(map(), String.t(), non_neg_integer()) :: [
  {String.t(), non_neg_integer()}
]

Gets the top K facets for a given facet path.

Parameters

  • facet_counts - The facet counts result from search/3
  • facet_path - The parent facet path to get children for
  • k - Number of top facets to return

Returns

  • List of tuples {facet_path, count} sorted by count descending

Example

top_categories = TantivyEx.Facet.get_top_k(facet_counts, "/electronics", 5)
# Returns: [{"/electronics/computers", 150}, {"/electronics/phones", 89}, ...]

multi_facet_query(field_name, facet_paths, occur)

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

Creates a multi-facet boolean query for filtering by multiple facets.

Parameters

  • field_name - The facet field name
  • facet_paths - List of facet paths to filter by
  • occur - How to combine the facets (:should, :must, :must_not)

Returns

  • {:ok, query_ref} on success
  • {:error, reason} on failure

Example

facets = ["/electronics/laptops", "/electronics/tablets"]
{:ok, multi_query} = TantivyEx.Facet.multi_facet_query("category", facets, :should)

search(searcher_ref, query_ref, collector_ref)

@spec search(reference(), reference(), reference()) ::
  {:ok, map()} | {:error, String.t()}

Performs a search with facet collection.

Parameters

  • searcher_ref - Reference to the searcher
  • query_ref - Reference to the query
  • collector_ref - Reference to the facet collector

Returns

  • {:ok, facet_counts} on success where facet_counts is a map
  • {:error, reason} on failure

Example

{:ok, facet_counts} = TantivyEx.Facet.search(searcher, query, collector)

to_string(facet_ref)

@spec to_string(reference()) :: {:ok, String.t()} | {:error, String.t()}

Gets the string representation of a facet.

Parameters

  • facet_ref - Reference to the facet

Returns

  • {:ok, facet_string} on success
  • {:error, reason} on failure

Example

{:ok, path} = TantivyEx.Facet.to_string(facet_ref)