Context Layer

Renta Context Layer lets AI assistants query Google BigQuery and ClickHouse data models through the context_layer MCP tool. An assistant selects dimensions, measures, and filters. Renta builds and runs the SQL using the model's warehouse connection.

Dimensions are fields used to group or filter data, such as country or order date. Measures are calculations such as total revenue or order count. You configure them in the data model.

Before you begin

Connect the Renta MCP Server to your assistant and prepare a data model.

Open a model in Tools > Context layers. If you need to create one, see the instructions for BigQuery or ClickHouse.
Set the scope to AI agents only or AI agents & Reverse ETL. Models with Reverse ETL only do not appear in list_models.
On the Access tab, grant access to the users or workspace groups that will query the model. Workspace owners already have access. For details, see Model access.
Configure the measures and metadata described below, then click Save changes.

Requests use the workspace and user associated with the token. Renta checks workspace membership and model access on each request. The four context_layer actions read data and do not modify warehouse records.

Configure measures

On the Measures tab, enable the aggregations an assistant can use for each column. For example, enabling SUM on revenue adds the measure revenue_sum. A column remains available as a dimension even when all its aggregation toggles are off.

Measures tab showing aggregation toggles for each model column

Numeric columns support all eight toggles. Other column types support COUNT and DISTINCT.

Toggle	Measure name	What it returns
SUM	`revenue_sum`	Sum of the column. Numeric columns only.
AVG	`revenue_avg`	Average of the column. Numeric columns only.
MIN	`revenue_min`	Smallest value. Numeric columns only.
MAX	`revenue_max`	Largest value. Numeric columns only.
MEDIAN	`revenue_median`	Approximate median. Numeric columns only.
P95	`revenue_p95`	Approximate 95th percentile. Numeric columns only.
COUNT	`order_id_count`	Number of non-null values in the column. Any column type.
DISTINCT	`order_id_distinct`	Number of distinct values in the column. Any column type.

Renta also adds count for the number of rows and, if the model has a unique key, unique_count for the number of distinct key values.

Choose aggregations that match what one row represents. For a model with one row per order, revenue_sum can represent total revenue. For rows that already contain averages or percentages, define how to weight them before aggregating. An average of daily averages does not generally equal the average across all orders.

Apply aggregations to multiple columns

Select columns to edit their aggregations together.

Selected model columns with aggregation controls in the toolbar

Select the checkboxes beside the columns. The header checkbox selects the currently visible rows.
Click an aggregation in the toolbar to enable it for the selected columns that support it. If it is already enabled for all eligible columns, clicking it disables it.
Use Clear to remove all aggregations from the selected columns, or Show Selected to hide unselected rows.

Describe the model

On the Metadata tab, give the model a name and description. Both appear in list_models and describe_model, so the assistant can use them to choose a model and interpret its results.

Metadata tab with the model name, model description, and column descriptions

State what one row represents, which dates the model covers, when it refreshes, and the units or currency. Include exclusions and any rules that affect the answer. For example:

Example model description

One row per completed order, identified by order_id.
Data starts on 2024-01-01 and refreshes daily at 06:00 UTC through the previous day.
Amounts are in USD, excluding VAT. Test orders are excluded.

Use this model for revenue and order counts by country, channel, or campaign.
For refunds, use the payments model. Refunded orders retain their original amount here.

Replace the dates and business rules in this example with those of your model.

In Column descriptions on the Metadata tab, describe what each field contains. Context Layer passes these descriptions to the AI assistant with the model schema. Add rules that apply to multiple fields to the model's Description.

If a field also has a description set through the REST API, the assistant receives the API version.

Query a model

Use list_models to find a model, then describe_model to get its field names. Call sample_field if you need to check field values before querying.

Action	Parameters	Result
`list_models`	Optional `source_id`	Accessible models with their IDs, names, descriptions, and warehouse types.
`describe_model`	`model_id`	Model definition, dimensions, measures, and any semantic overrides.
`sample_field`	`model_id`, `field_name`	Values or statistics for one field, plus query statistics.
`run_query`	`model_id` and selected fields	Result rows, column metadata, and query statistics.

The first two actions read saved metadata. The sample_field and run_query actions read your warehouse.

Check field values

Use sample_field to check values such as country codes before building a filter. For example, a country column might contain US rather than United States.

sample_field

{
  "action": "sample_field",
  "model_id": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "field_name": "country",
  "values_limit": 10
}

For string dimensions, values_limit controls how many values are returned: 50 by default, up to 500. The optional search parameter matches a case-insensitive prefix of up to 100 characters.

Field type	Sample result
String	Frequent values with counts and an approximate distinct-value count.
Boolean	Counts of true, false, and null values.
Number	Minimum, maximum, and the 10th, 50th, and 90th percentiles.
Time	Earliest and latest values, and the number of distinct days with data.
Numeric measure	Numeric field statistics and the measure's aggregate value.
COUNT measure	Total row count. Sampling a column COUNT measure does not exclude null values as run_query does.
DISTINCT measure	Approximate number of distinct values.
Calculated measure	Cannot be sampled. Use it in run_query.

For table-based models, sampling can also report whether a field belongs to a partition, clustering, or sorting key. These hints help you choose filters that reduce the amount of data read.

Run an analytical query

The following example returns up to 20 campaign-and-day groups with the highest lead totals in the last seven days. Replace the model ID and fields with values from list_models and describe_model. The example assumes date is a DATE column.

run_query

{
  "action": "run_query",
  "model_id": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "dimensions": ["e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.campaign"],
  "measures": ["e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.leads_sum"],
  "time_dimensions": [
    {
      "dimension": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.date",
      "granularity": "day",
      "date_range": "last_7_days"
    }
  ],
  "order": [
    {
      "member": "e2f1a3c4-5b6d-4e7f-8a90-1b2c3d4e5f60.leads_sum",
      "direction": "desc"
    }
  ],
  "limit": 20
}

Select at least one dimension, measure, or time dimension. Dimensions determine the grouping. A query with dimensions and no measures returns distinct combinations of those dimensions.

Query reference

Each query targets one model. To join warehouse tables, define the join in the model's SQL before querying it through Context Layer.

Field references

Use model_id.field_name in queries, including filters and sorting. Use the unqualified field_name only for sample_field.

Use measure names returned by describe_model, such as leads_sum or count. A column name by itself does not select an aggregation.

Filters

A filter specifies member, operator, and, when needed, values. Combine filters in nested groups with operator: "and" or operator: "or" and a filters array.

Operator	Values
`equals`, `not_equals`	Exactly one
`gt`, `gte`, `lt`, `lte`	Exactly one
`contains`, `not_contains`, `starts_with`, `ends_with`	Exactly one
`in`, `not_in`	One or more
`between`	Exactly two, both ends included
`is_null`, `is_not_null`	None

Dimension filters apply before aggregation. Measure filters apply after aggregation, for example to return campaigns with at least 100 leads. Combine these two kinds of filters with and. A group that mixes them with or is rejected.

Dates and time grouping

A time dimension selects a time field and optionally sets granularity and date_range. Supported granularities are hour, day, week, month, quarter, and year. Without a granularity, the query groups by the field's original values.

Set date_range to two ISO dates or a relative range:

Group	Tokens
Days	`today`, `yesterday`
Current period	`this_week`, `this_month`, `this_quarter`, `this_year`
Previous period	`last_week`, `last_month`, `last_quarter`, `last_year`
Rolling windows	`last_7_days`, `last_14_days`, `last_30_days`, `last_60_days`, `last_90_days`, `last_365_days`

Relative ranges use the current UTC date. Weeks start on Monday. Rolling ranges include today, so last_7_days covers today and the six preceding dates. Current-period ranges end today.

Both date boundaries are inclusive. For a timestamp field, the upper date boundary is the start of that date, not its end. Use a DATE dimension when you need to include whole calendar days.

Sorting and pagination

Each order entry must reference a selected field and use asc or desc. The default direction is asc.

Set limit to 1–10,000 rows (default 1,000). Use offset to skip rows, and specify a consistent order when paging. The response does not include a flag indicating that more rows are available.

Results

In a successful response, results are inside data. The tables show illustrative response fragments: MODEL_ID represents the model ID.

Field	Description	Example
`data.rows`	Result rows. Column names join the model ID and field name with `__`. A date grouped by month has a column name ending in `__date_month`.	`[{"MODEL_ID__date_month": "2026-09-01", "MODEL_ID__leads_sum": 120}]`
`data.schema_meta`	Column metadata: name and type. May also include the original warehouse type and the display format for a measure.	`[{"name": "MODEL_ID__leads_sum", "type": "int", "warehouse_type": "INTEGER"}]`
`data.query_stats`	Query execution statistics. All fields are listed below.	`{"source_type": "bigquery", "row_count": 1}`

The query_stats fields describe the executed query. For ClickHouse, billing, cost, cache, and slot usage fields are null.

query_stats field	Description	BigQuery example	ClickHouse example
`source_type`	Warehouse type.	`"bigquery"`	`"clickhouse"`
`bytes_processed`	Data volume in bytes: processed by BigQuery or read by ClickHouse.	`10485760`	`5242880`
`bytes_billed`	Data volume used for billing in BigQuery, in bytes.	`10485760`	`null`
`estimated_cost_usd`	Estimated query cost in US dollars.	`0.00006`	`null`
`cache_hit`	Whether BigQuery returned the result from its cache.	`false`	`null`
`slot_millis`	Total BigQuery slot usage time, in milliseconds.	`250`	`null`
`duration_ms`	Execution duration, in milliseconds.	`840`	`125`
`job_id`	BigQuery job ID or ClickHouse query ID.	`"bq_job_example"`	`"ch_query_example"`
`row_count`	Number of result rows after applying limit and offset.	`1`	`1`

Limits and query cost

The sample_field and run_query actions use your warehouse resources. The following limits apply per request:

Action	Byte limit	Query timeout
`sample_field`	5 GiB	30 seconds
`run_query`	10 GiB	60 seconds

BigQuery uses a maximum-bytes-billed setting. ClickHouse uses a maximum-bytes-read setting and stops queries that exceed it. These per-query limits do not set a total spending budget.

Filter on partition columns where possible. For ClickHouse, filters on leading sorting-key columns can also reduce reads. Reducing limit restricts returned rows but does not necessarily reduce the scan.

The default request quota is 360 per minute and 6,000 per hour, shared with other Customer API requests under the same user budget. Custom user limits take precedence.

Troubleshooting

Check the error message for the field, access rule, or warehouse limit involved. An MCP API error includes status_code and can include the underlying API response.

Problem	What to check
Model is missing from list_models	Check its AI scope and the user's access on the Access tab. Workspace owners have access to all models listed for AI use.
Access denied	Check workspace membership, model access, and the token's Context Layer Read permission.
Unknown field or invalid query	Refresh describe_model. Use qualified field names and sort only by selected fields.
Calculated measure cannot be sampled	Use the measure in run_query, or sample one of its underlying fields.
Scan limit or timeout exceeded	Narrow the date range or add filters that reduce the warehouse scan.
Rate limit exceeded	Reduce request frequency and retry after the limit resets.

Access from the REST API

The same operations are available with a Renta API token that has the Read permission in the Context Layer category.

Endpoint	Operation
`GET /v1/context_layer/models`	List models
`GET /v1/context_layer/models/{model_id}`	Describe a model
`GET /v1/context_layer/models/{model_id}/fields/{field_name}/values`	Sample a field
`POST /v1/context_layer/query`	Run a query

Terminal

curl -X GET "https://api.eu.renta.im/v1/context_layer/models" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

For REST sampling, use limit instead of the MCP parameter values_limit. REST also supports match=contains to search within string values. The default is match=prefix.

Semantic overrides add or replace field definitions, including descriptions and calculated measures. Read them with GET /v1/context_layer/models/{model_id}/semantics, replace them with PUT, and remove them with DELETE. Replacement requires Update, and removal requires Delete.