Configure

Semantic Model

A semantic model abstracts data into business terms and can also embed rules to control which data is visible or queryable for each user.

Data access

You can control which Inconvo will query within the semantic model. This control is available at table, column and relation levels.

Table

A table can be in one of three states:

1. Queryable Can be queried directly or joined into.
2. Joinable Can only be joined into from another table.
3. Off Cannot be queried or joined into.

Multi-tennant environments

In a multi-tennant environment we recommend setting a context filter on every Queryable table to ensure that data is scoped to a tenant.

Column

A column can be in one of two states:

1. On Can be selected in queries.
2. Off Cannot be selected in queries.

Relation

A relation creates a link between two tables to facilitate a join, it can be in one of two states:

1. On The join can be made.
2. Off The join cannot be made.

Context filters

Context filters are used to scope data to a configurable context and rely on context passed when creating a response.

Context filters are set on a per table basis, where a mapping is made between a field in the table and a key in the context object.

Multi-tennant databases

Context filters facilitate multi-tennant databases by allowing you to filter data based on the context of the request. Simply pass the value of your tenant identifier e.g. organisationId in the context when creating a response and create context filters on queryable tables to retrieve only the data relevant to a specific tenant.

For example if you have a table orders with a column organisation_id which is your tenant identifier.

You must set the following context filter on the orders table.

WHERE orders.organisation_id = context.organisationId;

When creating a conversation you must pass context in the body the request:

"context": {
    "organisationId": 1
}

Within this conversation data returned from the orders table will be scoped to the organisation with an id of 1.

WHERE orders.organisation_id = 1;

Table prompts

A Table prompt is a block of plain‑language text containing contextual rules for interpreting the data of a particular table. Adding relevant table prompts ensures Inconvo has the business context required to correctly interpret table data.

For example, given a table users with the following schema in an ecommerce analytics database:

CREATE TABLE public.users (
    organisation_id integer NOT NULL,
    id              integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    address         varchar(255),
    email           varchar(255),
    password        varchar(255),
    name            varchar(255),
    city            varchar(255),
    longitude       double precision,
    birth_date      date,
    zip             char(5),
    latitude        double precision,
    created_at      timestamp without time zone,
    last_order_at   timestamp without time zone,
    FOREIGN KEY (organisation_id) REFERENCES public.organisations(id)
);

We can add the following table prompt:

Users are also referred to as accounts.
A user is considered a customer if the last_order_at is not null.
New customers over a time period are those who have every order after the start of the time period.

Adding this prompt unlocks new answers for the user. For example, Inconvo can now answer questions like:

• “How many new customers have we had in the last month?”
• “What is the average order value for accounts in San Francisco?”
• “What percentage of users added in the last quarter are not yet customers?”

Computed columns

Computed columns are columns that are not present in the database but can be derived from existing columns. They are defined using a mathematical expression and can be used in queries just like any other column.

Given an example table orders with the following schema:

CREATE TABLE public.orders (
    organisation_id integer NOT NULL,
    id              integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    user_id         integer,
    product_id      integer,
    subtotal        double precision,
    tax             double precision,
    discount        double precision,
    created_at      timestamp without time zone,
    quantity        integer,
    FOREIGN KEY (organisation_id) REFERENCES public.organisations(id),
    FOREIGN KEY (user_id) REFERENCES public.users(id),
    FOREIGN KEY (product_id) REFERENCES public.products(id)
);

There is no column for the total value of an order, but we can easily create a computed column total using the following expression:

total = subtotal - discount + tax

Now we can ask questions that require the total order value e.g. “What was our revenue in the last month?”

Column units

Column units are used to specify the unit of measurement for numerical columns.

For example, if you have a column total in a table orders that represents the price of a product in USD, you can set the unit to USD.

Now responses to queries that include the total column will include the unit of measurement in the response.

Q: What was our total revenue in the last month?

A: Your total revenue for last month (April 2025) was $3,059,223.96.

Considerations

Semantic Model Quality

Your semantic model is provided as context to guide Inconvo during data retrieval. A well designed semantic model augments Inconvo’s data retrieval capabilities.

You can use evaluations to run queries and view Inconvo’s trace. This will help you identify changes required on your semantic model to steer Inconvo for your data.