Shape First: Size a Result Before Reading It

Analyse your data with your AI client · Shape first

Know it is 60 million rows before you ask for them

Columns, a row-count estimate, the size of one row and of the whole result, and how many rows fit your budget. No rows are sent.

Personal Core and up Runs on your Network Agent Sempre in sola lettura

Hai bisogno di aiuto? Chiedi pure a noi. Apri Supporto Accedi a Query Streams (menu in alto a destra → Supporto) e inviaci un messaggio. Persone reali lo leggono, e "Non so cosa mi stia chiedendo questa schermata" è una domanda assolutamente legittima.

What your Network Agent does for you

Your AI client learns the size of a result before it pays for it. Your Network Agent reads the first rows, measures them, estimates the total and stops the query, then sends that back with no rows at all. The shape of a 60-million-row table comes back in under a second.

Asking for rows is how an AI client usually finds out a table is huge: the result floods in, gets cut, and the question is asked again. Shape first turns that around. Your AI client asks for the shape, then decides: a few rows, a profilo, an aggregate, or a narrower query.

Situazione	Before	With Shape first
“What is in the inventory detail table?”	A thousand raw rows, cut by the client, size unknown.	About 60 million rows, its columns, tokens per row, and the empty columns named.
“Profile it.”	Nobody can tell how long that will take.	The shape reports how fast the database delivers rows, so the client can size the profile.
A join across two big tables	Runs until it times out.	An estimate first, so the client adds a filter.

The plan it needs

Piano	This capability	Note
Gratuito	Not on this plan	Works as it always has, with standard results.
Personal Core, Personal Plus	Incluso	Part of Context management.
Business Core, Business Plus, Business Max	Incluso	Part of Context management.
Enterprise Core, Plus, Max	Incluso	Part of Context management.

Why it is on paid plans: your Network Agent does the heavy lifting next to your database, so the rows stay in your network and your AI client spends its attention on the thinking. That groundwork is what the paid plans add.

The Free plan works as it always has. Paid plans add the Analytic toolset. Free is a plan you keep: MCP, the REST API, federated queries and alerts, with the same results as before. Plan names and prices are on the pagina dei prezzi.

How to ask

You do not call tools yourself. Ask in plain words and your AI client picks the tool. Three asks that bring this capability in:

Claude

ChatGPT

Cursore

Codice Claude+10 moreSola lettura

How big is the stock movement table? Do not fetch rows yet.

qs_run_query · mode=shape

Which columns in that table are always empty?

qs_run_query · mode=shape

Would the whole result fit in this conversation?

qs_run_query · mode=shape

Groundwork done on your Network Agent, inside your network accesso effettuato nella scheda Attività MCP

For people who read tool lists: mode: shape SU query_di_esecuzione_qs e query_salvata_eseguita_qs. The answer has a shape block with the row estimate and where it came from, tokens per row, the whole-result estimate, whether it fits the budget and how many rows do, and the empty columns. See it on the Tools tab.

What comes back

Claude

ChatGPT

Cursore

Codice Claude+10 moreSola lettura

What is in the inventory detail table? Do not pull rows, just tell me how big it is.

qs_run_query · mode=shape

It is large: about 60 million rows and 20 columns, far more than any conversation can hold. 7 of the 20 columns were empty in every sampled row.

measure	value
rows (from the catalogue)	about 60,000,000
fits the budget	NO
rows sent	0

I suggest a profile, or an aggregate by month, rather than rows. Shall I?

Groundwork done on your Network Agent, inside your network under a second · no rows sent

Row estimate: From the database’s own catalogue when it keeps one, otherwise a count that stops early and says so. Approximate figures are reported as estimates.
Tokens per row: Measured from the first rows, so your AI client can work out how many will fit.
Fits the budget: Whether the whole result fits the size this call would use, and how many rows do.
Empty columns: Columns with no value in any sampled row, by name.
Timing: How fast the database delivered the sample and roughly how long a full scan would take, so a later profile can be sized too.

What it does not help with

It does not answer the question itself. It tells your AI client how big the answer is.
The row count of a join or a filtered query is an estimate or a capped count, not an exact total.
Tokens per row come from a sample. A table whose later rows are much wider will cost more.
A federated saved query cannot be shaped.

Limiti

A few hundred tokens for a narrow result; a wide one costs more because the column list is the answer.
The statement does start on your database before the agent stops it, so a shape needs the key’s run-queries scope.
The usual query timeout applies: 60 seconds by default, at most 300. A shape finishes quickly.

Impostazioni

No setting of its own. The rows that fit follow your Result size on the MCP page’s Context tab, card What reaches your AI assistant.

When your AI client says no

When the server refuses, your AI client receives a code and one sentence, and usually relays it. Quoted sentences are the server’s own words; the parts in italics stand for the ids a real message names.

Codice	What the server says	Cosa fare
`MCP_FEATURE_NOT_INCLUDED`	“Your plan does not include context management; schema by business area, shaped results and a size budget are available on Personal Core.”	Your AI client carries on without the input and gives you the plain result. To keep the capability, move up to Personal Core.
`MCP_AGENT_VERSION_TOO_OLD`	“Update the Network Agent to shape results at the source; this agent cannot answer mode=shape yet, so ask for rows (omit mode) until it is updated.”	Agents update themselves. Check the agent under Dati → Agenti dati.
`MCP_INVALID_INPUT`	A mode other than rows, shape, profile or quality, or a federated saved query asked to shape.	Ask for rows, or shape a single-source query.
`MCP_AGENT_NON_CONNESSO`	The Network Agent that owns the connector is not connected right now.	Apri Dati → Agenti dati and start the agent on its computer.

Esempi

“Is the daily inventory table safe to query?”

Your AI client learns it holds about 60 million rows and suggests a profile of the first million rows, or a monthly aggregate, instead of reading it.

“Which columns can we ignore?”

The shape names the columns that are empty in every sampled row, so the client leaves them out of the next query.

Ancora bloccato? Apri Supporto Accedi a Query Streams e comunicaci a quale passaggio ti trovi e cosa visualizzi. Ti aiuteremo a connetterti.

Facts source

Setup trouble?

Agent shows Offline, or Test connection and Browse are greyed out? Check that the Agent is online → Is the Agent online?

What your Network Agent does for you

The plan it needs

How to ask

What comes back

What it does not help with

Limiti

Impostazioni

When your AI client says no

Esempi

“Is the daily inventory table safe to query?”

“Which columns can we ignore?”

Related

Facts source

Condividi questo articolo :