Bluge Documentation

Bluge is a modern text indexing library written in Go. It supports various field types, query types, and advanced search features like BM25 scoring and highlighting.

Supported Field Types

• Text
• Numeric
• Date
• Geo Point

Supported Query Types

• Term, Phrase, Match, Match Phrase, Prefix
• Conjunction, Disjunction, Boolean
• Numeric Range, Date Range

Aggregations

Bluge provides extendable aggregations including:

• Bucketing: Terms, Numeric Range, Date Range
• Metrics: Min, Max, Count, Sum, Avg, Weighted Avg, Cardinality Estimation (via HyperLogLog++), and Quantile Approximation (via T-Digest).

Bluge's geo support is a Go adaptation of the Lucene 5.3.2 sandbox geo support. When working with geographic data, keep the following conventions in mind:

• Coordinate Types: All APIs use float64 for longitude and latitude values.
• Coordinate Order: When providing points in function arguments or receiving them in return values, always use the order longitude, latitude (lon, lat).
• Bounding Boxes:
  • High-level APIs: Use TopLeft and BottomRight to describe bounding boxes. Note that these may not map cleanly to min/max longitude/latitude when crossing the dateline.
  • Low-level APIs: Use min/max longitude/latitude. If you are using high-level bounding boxes that cross the dateline, you must use the higher-level code to split the boxes into multiple parts before using low-level APIs.

To index data, use bluge.DefaultConfig(path) to define the index location, then open a writer using bluge.OpenWriter(config). Documents are created using bluge.NewDocument(id) and fields are added via methods like AddField. Use writer.Update(doc.ID(), doc) to persist the document to the index. Always ensure you defer writer.Close() to flush changes and release resources.

    config := bluge.DefaultConfig(path)
    writer, err := bluge.OpenWriter(config)
    if err != nil {
        log.Fatalf("error opening writer: %v", err)
    }
    defer writer.Close()

    doc := bluge.NewDocument("example").
        AddField(bluge.NewTextField("name", "bluge"))

    err = writer.Update(doc.ID(), doc)
    if err != nil {
        log.Fatalf("error updating document: %v", err)
    }

The FieldConsumer interface allows a field to 'consume' the content of other fields during the Analyze() phase of a document. This is useful for creating composite fields that depend on the analyzed output of other fields in the same document.

To implement this, define a type that satisfies the interface:

type MyCompositeField struct {
    // ...
}

func (m *MyCompositeField) Consume(f bluge.Field) {
    // Process the field f
}

A virtual field allows you to define a field that the index treats as if every document contains those terms, even though the data is not physically stored in the index. This is useful for creating catch-all search behaviors or metadata overlays. Use the WithVirtualField(field Field) method on a Config object to register it.

Note: The field must be analyzed before being passed to WithVirtualField to ensure the index configuration is correctly updated.

Use DefaultConfig(path) to create a configuration for an index stored at the specified path. Alternatively, use InMemoryOnlyConfig() for an index that exists only in memory, or DefaultConfigWithDirectory(df) to provide a custom directory implementation via a function df func() index.Directory.

By default, a Config instance includes:

• A Logger (defaults to ioutil.Discard).
• DefaultSearchField set to "_all".
• DefaultSearchAnalyzer using a standard analyzer.
• DefaultSimilarity using BM25 similarity.
• A virtual field "_all" that acts as a catch-all for documents.

Bluge uses FieldOptions to control how fields are handled during indexing and retrieval. You can chain these options when creating or configuring a TermField.

Available options:

• Index: Enables indexing for the field.
• Store: Stores the original value for retrieval.
• SearchTermPositions: Stores term positions (required for proximity searches).
• HighlightMatches: Enables highlighting of search matches.
• Sortable: Enables the field to be used for sorting.
• Aggregatable: Enables the field to be used for aggregations.

A WildcardQuery finds documents containing terms that match a wildcard pattern.

• * matches any sequence of 0 or more characters.
• ? matches any single character.

The SortBy(order []string) method is a convenience for specifying sort orders using field names.

Rules for the order slice:

• A string like "field_name" sorts that field in ascending order.
• A prefix of "-" (e.g., "-field_name") sorts that field in descending order.
• The special field "_score" can be used to sort by the document score.

Example:

// Sort by price descending, then by name ascending
s.SortBy([]string{"-price", "name"})