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"`
}