Comprendre akko-mcp-trino en cinq niveaux

1 · Chercher

« Quel segment de clients détient le plus gros solde total ? »

L’agent ne connaît pas les tables. Il cherche avec quatre mots de la question, en un seul tool call sur tous les catalogs qu’il a le droit de voir.

search_columns {"text": "customer segment account balance"}

2 · Mot par mot

Aucune colonne ne porte les quatre mots, alors le serveur cherche chaque mot

Chaque résultat dit quels mots l’ont trouvé, et "partial": true prévient l’agent. Les colonnes marquées sont celles que sa réponse utilisera.

• crm.accounts.balanceaccountbalanceretenue
• crm.customers.segmentcustomersegmentretenue
• crm.accounts.customer_idcustomerretenue
• crm.transactions.account_idaccount
• crm.transactions.amountaccount

"partial": true,
"hint": "No table or column holds every word together, so these are partial matches, each found by the words it lists: pick the right one, or search again with a single word from a column or table name, then call describe_table on the table."

3 · Une jointure fausse

L’agent joint sur c.customer_id, une colonne que customers n’a pas

Il écrit tout de suite la requête, sans lire la table customers.

execute_query {"sql": "SELECT c.segment, SUM(a.balance) AS total_balance FROM demo.crm.customers c JOIN demo.crm.accounts a ON c.customer_id = a.customer_id GROUP BY c.segment ORDER BY total_balance DESC LIMIT 1", "max_rows": 1}

4 · L’erreur guide

L’erreur dit quelle table lire

Depuis la 0.7.0, une erreur porte un kind et, pour une colonne introuvable, un hint qui nomme la table à lire.

{"error": "TrinoUserError(type=USER_ERROR, name=COLUMN_NOT_FOUND, message=\"line 1:105: Column 'c.customer_id' cannot be resolved\", query_id=20261101_211014_00019_85v63)", "kind": "column", "identifier": "c.customer_id", "hint": "Read the columns of demo.crm.customers with describe_table, then write the query again with a column it has."}

5 · Lire la table

customers a une colonne id, pas customer_id

L’agent suit le hint et lit les colonnes de customers.

describe_table {"catalog": "demo", "schema": "crm", "table": "customers"}

{"columns": ["Column", "Type", "Extra", "Comment"], "rows": [["id", "integer", "", ""], ["full_name", "varchar", "", ""], ["email", "varchar", "", ""], ["country", "char(2)", "", ""], ["segment", "varchar", "", "Retail or business customer"]], "truncated": false}

6 · Corriger et répondre

Le segment business, avec 17 620,75 de solde total

L’agent relance la requête avec c.id = a.customer_id. Trino calcule sur les seuls clients que Carol a le droit de voir : les 17 620,75 sont en EUR, les deux comptes de Sofia Ruiz, car le row filter de Carol écarte les clients business hors d’Europe. L’agent cite les colonnes utilisées. Le même chemin revient dans 4 des 5 essais de cette question.

execute_query {"sql": "SELECT c.segment, SUM(a.balance) AS total_balance FROM demo.crm.customers c JOIN demo.crm.accounts a ON c.id = a.customer_id GROUP BY c.segment ORDER BY total_balance DESC LIMIT 1", "max_rows": 1}

{"columns": ["segment", "total_balance"], "rows": [["business", "17620.75"]], "row_count": 1, "truncated": false}

The customer segment that holds the largest total account balance is the business segment, with a total balance of 17620.75.

The columns relied on are:
- demo.crm.customers.segment
- demo.crm.accounts.balance
- demo.crm.customers.id
- demo.crm.accounts.customer_id