TantivyEx.Error (TantivyEx v0.4.1)

View Source

Comprehensive error handling for TantivyEx with structured error types that mirror Tantivy's Rust error hierarchy.

This module provides proper Elixir error types and messages for all TantivyEx operations, offering better error diagnostics and handling capabilities.

Error Types

All errors implement the Elixir Exception behavior and provide structured error information with context, suggestions, and categorization.

Core Error Categories

  • AggregationError - Errors during aggregation operations
  • IoError - File system and I/O related errors
  • LockError - Index locking and concurrency errors
  • FieldError - Schema field-related errors
  • ValidationError - Document and data validation errors
  • SchemaError - Schema definition and compatibility errors
  • SystemError - System resource and configuration errors
  • QueryError - Query parsing and execution errors
  • IndexError - Index creation and management errors
  • MemoryError - Memory management and limits errors
  • ConcurrencyError - Thread pool and parallelism errors

Usage

# Match on specific error types
case TantivyEx.Document.add(writer, doc, schema) do
  {:ok, result} -> handle_success(result)
  {:error, %TantivyEx.Error.ValidationError{} = error} -> handle_validation_error(error)
  {:error, %TantivyEx.Error.MemoryError{} = error} -> handle_memory_error(error)
  {:error, error} -> handle_generic_error(error)
end

# Get error details
error = %TantivyEx.Error.FieldError{
  message: "Field 'title' not found in schema",
  field: "title",
  operation: :search,
  suggestion: "Check field name or add field to schema"
}

IO.puts(Exception.message(error))
# => "Field error in search operation: Field 'title' not found in schema. Suggestion: Check field name or add field to schema"

Error Enhancement

All TantivyEx modules should use TantivyEx.Error.wrap/2 to convert raw errors into structured error types:

case Native.some_operation(args) do
  {:ok, result} -> {:ok, result}
  {:error, reason} -> {:error, TantivyEx.Error.wrap(reason, :operation_context)}
end

Summary

Types

t()

Standard error type for TantivyEx operations.

Functions

retryable?(arg1)

Checks if an error is retryable based on its type and context.

severity(arg1)

Returns the severity level of an error.

to_log_format(error)

Converts an error to a loggable format with structured metadata.

wrap(error, context \\ :unknown)

Wraps a raw error into a structured TantivyEx error.

Types

t()

@type t() :: {:error, atom() | String.t()}

Standard error type for TantivyEx operations.

Common error reasons include:

  • :invalid_parameters - Function was called with invalid parameters
  • :not_implemented - Feature is not yet implemented
  • :resource_not_found - Requested resource was not found
  • :resource_limit_exceeded - Memory or resource limits were exceeded
  • :index_error - Error related to index operations

Functions

retryable?(arg1)

@spec retryable?(Exception.t()) :: boolean()

Checks if an error is retryable based on its type and context.

Examples

iex> TantivyEx.Error.retryable?(%TantivyEx.Error.LockError{})
true

iex> TantivyEx.Error.retryable?(%TantivyEx.Error.SchemaError{})
false

severity(arg1)

@spec severity(Exception.t()) :: :info | :warning | :error | :critical

Returns the severity level of an error.

Examples

iex> TantivyEx.Error.severity(%TantivyEx.Error.ValidationError{})
:warning

iex> TantivyEx.Error.severity(%TantivyEx.Error.SystemError{})
:error

to_log_format(error)

@spec to_log_format(Exception.t()) :: map()

Converts an error to a loggable format with structured metadata.

Examples

iex> error = %TantivyEx.Error.FieldError{field: "title", operation: :search}
iex> TantivyEx.Error.to_log_format(error)
%{
  level: :warning,
  message: "Field error in search operation",
  category: "field_error",
  field: "title",
  operation: :search,
  retryable: false
}

wrap(error, context \\ :unknown)

@spec wrap(any(), atom()) :: Exception.t()

Wraps a raw error into a structured TantivyEx error.

This function analyzes the error content and context to determine the most appropriate error type and provides enhanced error information.

Parameters

  • error - The raw error (string, atom, or map)
  • context - The operation context (atom) for better error categorization

Examples

iex> TantivyEx.Error.wrap("Field 'title' not found", :search)
%TantivyEx.Error.FieldError{
  message: "Field 'title' not found",
  field: "title",
  operation: :search,
  suggestion: "Check field name or add field to schema"
}

iex> TantivyEx.Error.wrap("Memory limit exceeded", :indexing)
%TantivyEx.Error.MemoryError{
  message: "Memory limit exceeded",
  operation: :indexing,
  suggestion: "Increase memory limit or reduce batch size"
}