Skip to main content

Secondary Indexes

Tigris supports adding secondary indexes for collections. See indexing concepts for the full details.

Creating an Index​

To add an index to a field in a collection, add index: true to the field. Below is an example of adding indexing to two fields for a User collection.

type User struct {
    Email      string `tigris:"primary_key,index"`
    Name       string `tigris:"index"`
}

err = db.CreateCollections(ctx, User{})

If you are adding an index to an existing collection, you will need to log into the Tigris web console to initiate a build of the indexes for that collection. See this concepts page for how to do this.

Getting the state of an index​

An index can be in INDEX ACTIVE state which means the index is being used for queries or in INDEX WRITE MODE where the index is still being built.

The method Describe() will return back the status of each index in the collection.

users := tigris.GetCollection[User](db)
describe, _ := users.Describe()
fmt.Println(describe.Indexes)

//returns:
[
    {
        name: '_tigris_created_at',
        state: 'INDEX ACTIVE',
        fieldsList: []
    },
    {
        name: '_tigris_updated_at',
        state: 'INDEX ACTIVE',
        fieldsList: []
    },
    { name: 'email', state: 'INDEX WRITE MODE', fieldsList: ["email"] },
    { name: 'name', state: 'INDEX ACTIVE', fieldsList: ["name"] },
]

Querying​

When running a Read, ReadOne and ReadWithOptions, Tigris will automatically look to see if a secondary index can be used to satisfy the query.

iter, err := users.Read(ctx, filter.GtString("name", "bob"))

Sorting​

An index can also be used to define the sort order of the documents returned. This can be done by using a single index in the sort.

it, err = catalog.ReadWithOptions(ctx, filter.All, fields.All,
    &tigris.ReadOptions{
        Sort: sort.Descending("name"),
    },
)

Explain​

Tigris has an explain method to show how the Tigris query planner would run for a query. For example:

explain, err := users.Explain(ctx, filter.GtInt("Popularity", 2), nil, nil)
fmt.Println(explain)
// will return:
{
  collection: 'user',
  readType: 'secondary index',
  filter: '{"name":"bob"}',
  keyRangeList: [ "bob" ],
  field: 'name'
}