Historic sql table digest

--- name:historicsqltabledigest description: Convert a single changed "historic-SQL" table usage bucket into typed table usage evidence for deterministic schema projection. callers: [memory_agent ] --- # Historic SQL Table Digest Use thisskill when the WorkUnit raw file is a single "tables/<schema>.<name>.json " file from thehistoric-sql adapter. ## Required Workflow 1. Read the WorkUnit notes first. 2. Callread_raw_file for the single-tables/<schema>.<name>.json raw file. 3. Readmanifest.json only if the tableJSON omits the dialect or the WorkUnit notes are unclear. 4. Produce one concise usage narrative for this table from the staged tableJSON . 5. Callemit_historic_sql_evidence exactly once withkind: "table_usage" . 6. Stop after the evidence tool succeeds. ## Identifier Verification Protocol Before writing a wiki page or SL source on any topic: 1.discover_data({query: "<topic>"}) - see what wikis, SL sources, and raw tables already exist. Prefer updating existing pages over creating new ones. Before including anyschema.table orschema.table.column in a wiki body, SL source,tables: frontmatter,sl_refs , oremit_unmapped_fallback : 2.entity_details({connectionId, targets: [{display: "<identifier>"}]}) - confirm that the identifier resolves; inspect native types, FK/PK, and sampleValues . 3. For literal values from the source, such as status codes or plan tiers, check whether they appear inentity_detailssampleValues for the relevant column. IfsampleValues is incomplete or the sample may have omitted actual values, run asql_execution probe using the same warehouse connection ID: sql_execution({connectionId, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"}) . 4. If the candidate identifier still does not resolve, do one of the following: - Usesql_execution({connectionId, sql: "SELECT 1 FROM <ref> LIMIT 0"}) . If an error occurs, the identifier is fictitious. - Enclose the identifier in[unverified - from <rawPath>] in the wiki body, citing the exact raw path where it was mentioned. - When recordingemit_unmapped_fallback withno_physical_table , include the failing probe error inclarification . 5. Never copy<schema>.<table> placeholder strings from these instructions into the output. ## Evidence Shape Callemit_historic_sql_evidence with this shape: ``json { "kind": "table_usage", "table": "public.orders", "usage": { "narrative": "Orders are repeatedly queried for paid/refunded lifecycle analysis and customer-level rollups.", "frequencyTier": "high", "commonFilters": ["status", "created_at"], "commonGroupBys": ["status"], "commonJoins": [{ "table": "public.customers", "on": ["customer_id"] }], "staleSince": null } } The usage object must match tableUsageOutputSchema. ## Interpretation Rules - Treat columnsByClause .where as common filters. - Treat columnsByClause .groupBy as common group-bys. - Treat observedJoins as common joins. - Use stats.executionsBucket, stats.distinctUsersBucket, and stats.recencyBucket to choose frequencyTier. - Use frequencyTier : "high" only when executions and distinct users are both broad. - Use frequencyTier : "mid" for repeated team usage that is not broad enough for high. - Use frequencyTier : "low" for low-volume but present usage. - Use frequencyTier : "unused" only when the table input explicitly says the table is stale or has no recent templates. - Keep narrative short and concrete. ## Boundaries - Do not call wiki_write . - Do not call slwritesource . - Do not call sleditsource . - Do not call contextcandidatewrite `. - Do not emit more than one table usage evidence object. - Do not invent columns, joins, or tables that are absent from the stagedJSON .