Skip to main content

​
Overview

Custom models let you add your own tables, metrics and dimensions to the semantic layer, next to the built-in Interact models. You write them as Ossie YAML files (*.ossie.yaml) in a GitHub repository, usually the dbt or Dataform repository that builds the tables. Interact reads the files when you sync. Keeping the models in Git means they are reviewed and versioned together with the transformations that produce the tables. Prerequisites:
  • You are an organization admin
  • Data mapping has a Warehouse - read connector that can read the tables your models use
  • A GitHub repository with one or more *.ossie.yaml files (see Ossie model reference)
  • A GitHub personal access token with read access to that repository
An organization has one custom semantic layer, connected to one repository.

​
Step 1: Add a GitHub connector

1

Create a personal access token

In GitHub, go to Settings → Developer settings → Personal access tokens and create a token. A fine-grained token only needs Contents: Read-only on the repository that holds your models.
Treat the token like a password. Interact stores it encrypted.
2

Add the connector in Interact

Go to Settings → Connectors, click Add connector and choose GitHub. Paste the token in Personal access token. Organization is optional.
3

Save the connector

Click Save connector.

​
Step 2: Configure the semantic layer

Go to Settings → Semantic layer and click Configure semantic layer.
The button is disabled until there is an active GitHub connector.
Click Save. You return to the semantic layer list.

​
Step 3: Sync the models

Click Sync on the Custom models tab. Interact reads every *.ossie.yaml and *.ossie.yml file under the model path on the chosen branch, checks it, and loads the models. Other YAML files in the folder, such as dbt schema.yml, are ignored. A message tells you how many files loaded and how many were skipped.
Sync is manual. Push your changes to the branch first, then click Sync in Interact. Each sync replaces all custom models with what is on the branch at that moment.

​
The Custom models tab

Each dataset from your files is listed with: Click a row to see the dataset’s source, dimensions, metrics and relationships.

​
Badges and errors

The column check only works for datasets whose source is a plain table reference (project.dataset.table). Datasets with a SELECT as source are not checked.

​
Edit or remove the semantic layer

Click Edit on the Semantic layer page to change the repository, branch or path. Sync again after changing them. To remove it, open Edit and use Delete semantic layer in the Danger Zone. This deletes the configuration and the synced models. Your Git repository is not touched.

​
Troubleshooting

Check the branch name and that the token can access the repository. Private repositories need a token with access to that repository.
Interact reads the repository tree in one request. Very large repositories go over GitHub’s limit. Use a narrower Model path.
Files must end in .ossie.yaml or .ossie.yml and live under the model path. Check the path has no typo and the files are pushed to the selected branch.
The message names the file and the first problem, for example a missing datasets list or invalid YAML. See the Ossie model reference.
A query asked for members from two datasets that have no relationship between them. Add a relationship from the detailed dataset to the one it looks up. See Relationships.