Skip to main content

Data Modeling

Tigris enables the data models to be declared as part of the application code. These data models are then converted to appropriate objects, such as collections, on the backend.

Declaring Models​

Models are regular Go structs composed of basic Go types or custom types. Field properties can be modified using optional "tigris" tag.

type Catalog struct {
    Id         int `tigris:"primary_key,autoGenerate"`
    Name       string `tigris:"searchIndex"`
    Price      float64
    Brand      string `tigris:"searchIndex,facet"`
    Labels     string `tigris:"searchIndex,facet"`
    Popularity int
    VecField   [1536]float64 `json:"vec_field" tigris:"vector"`
}

Create the Collection​

Creates the collection with the model and any new operation will see the changes.

err := db.CreateCollections(ctx, &Catalog{})

This declaration will create a collection named catalogs.

Collection Names​

The name of the collection is derived from the struct name. The struct name is pluralized to snake_cases as collection name. For example, the struct name Catalog is converted to catalogs as the collection name. While the struct name CatalogDetail is converted to catalog_details as the collection name.

Field Names​

The name of the fields in the struct are used as the field names in the collection's schema. There is no conversion performed by default. To have fields in the collection schema with a different name, you can configure json field tags as can be seen below

type Catalog struct {
    Id         int `json:"id" tigris:"primaryKey,autoGenerate"`
    ProductName string `json:"product_name"`
    Price      float64
    Brand      string
    Labels     string
    Popularity int
    VecField   [1536]float64 `json:"vec_field" tigris:"vector"`
}

Unexported fields and fields annotated with json:"-" or tigris"-" are not persisted in the collection.

Field tags​

Fields behavior can be modified and enriched using tigris struct tag.

Check available tags and example usage..

Embedded Data Model​

Tigris offers rich documents that enable embedding related data in a single document. Embedded models allow applications to complete database operations with fewer queries or updates, thus reducing query activity and increasing efficiency.

Below is an example of embedded data model. We first define the Product type and then embed it inside the Order type.

type Product struct {
    Id       int `tigris:"primaryKey,autoGenerate"`
    Name     string
    Quantity int
    Price    float64
}

type Order struct {
    Id     int `tigris:"primaryKey,autoGenerate"`
    UserId int

    Products []Product
}

Primary Key​

A primary key uniquely identifies a document in the collection and enforces the unique constraint. In the absence of a user-defined primary key, it is auto-generated.

Embedding Tigris metadata model​

The primary key can be implicitly defined by embedding Tigris collection model, like shown below:

type Catalog struct {
    tigris.Model

    Name       string
    Price      float64
    Brand      string
    Labels     string
    Popularity int
}

It adds an implicit ID field of type UUID to the collection model. This is useful when the user document model doesn't have unique set of fields, or the set of fields is not suitable to be a primary key due to size, type, sensitive content, etc...

The ID field is automatically populated when the document inserted into collection.

For example using the model above:

catalog := tigris.GetCollection[Catalog](db)

product := Catalog{Name: "fiona handbag", Price: 99}
_, err = catalog.Insert(context.Background(), &product)

The ID field is automatically populated.

Note: you do not need to explicitly mention this id: string field to your schema definition. It is available implicitly (as long as you don't have primary key defined).

Explicit ID field​

You can explicitly set the type of the field with name "ID" or "Id". This field is automatically marked as the primary key.

For example:

type Catalog struct {
    ID time.Time
    Name       string
    Price      float64
    Brand      string
    Labels     string
    Popularity int
}

Defining Primary Key​

One or more fields in the struct can be specified as primary key by configuring tigris primary key field tag. While the autoGenerate tag can be used to instruct Tigris to automatically generate the values for this field. The example below demonstrates a model with a single primary key field

type CatalogDetail struct {
    Id    int `tigris:"primaryKey,autoGenerate"`
    Spec  string
    Description string
}

Composite Primary Key​

Composite primary keys are also supported but in case of composite keys order of the fields is important. The example below demonstrates how the order of the fields are defined in case of a composite primary key

type CatalogDetail struct {
    Id    int `tigris:"primaryKey:1,autoGenerate"`
    Spec  string `tigris:"primaryKey:2"`
    Description string
}

Vector Field​

Tigris supports vector fields. Vector fields are used to store the vector embeddings of the documents. These embeddings are used to perform vector search.

type CatalogDetail struct {
    Id    int `tigris:"primaryKey,autoGenerate"`
    Spec  string
    Description string
    VecField [1536]float64 `json:"vec_field" tigris:"vector"`
}