improvement(azure-data-explorer): warn that ingest-from-query matches columns by position

Kusto aligns an ingested query result to the target table on column type
and order, never on column name, so a query projecting the right columns
in the wrong order lands data in the wrong columns without erroring.

Surfaces that in the tool description and param the model reads, in the
wand prompt that generates the query, in the rollup skill's steps, and in
the docs. Also verifies the target schema first rather than after.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/azure_data_explorer.mdx

@@ -41,6 +41,7 @@ A few things worth knowing before you build:
 - **Results are capped at 10,000 rows.** Every result reports `rowCount`, `totalRowCount`, and `truncated`, so a query that returned more than the cap says so rather than quietly looking complete. Aggregate with `summarize` or bound the query with `take` instead of pulling raw rows.
 - **Ingest Rows Inline is for small batches.** It is ideal for tens or hundreds of rows from a workflow run. For continuous or high-volume loading, use Azure Data Explorer's queued or streaming ingestion instead.
 - **Ingest From Query defaults to `set-or-append`**, which adds to an existing table. `set-or-replace` discards everything already in the target table — pick it only when you mean to rebuild the rollup from scratch. For a large backfill, turn on the background option and poll Show Operations with the operation ID it returns.
+- **Ingest From Query matches columns by position, not by name.** Kusto aligns the query result to the target table on column type and order, so a query that projects the right columns in the wrong order ingests data into the wrong columns without erroring. End the query with an explicit `project` in the table's column order, and confirm with Show Table Schema first.
 - **Drop Table is permanent.** It deletes the table and its data. Give an agent the `viewers` role rather than `admins` unless a workflow genuinely needs to change schema.
 {/* MANUAL-CONTENT-END */}
 
@@ -332,7 +333,7 @@ Push rows directly into an Azure Data Explorer table with .ingest inline. Data i
 
 ### Azure Data Explorer Ingest From Query
 
-Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow.
+Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow. Kusto matches the query result to the target table by column type and position, NOT by column name, so project the columns in exactly the table's order or the data lands in the wrong columns.
 
 #### Input
 
@@ -346,7 +347,7 @@ Materialize the result of a KQL query into a table with .set, .append, .set-or-a
 | `database` | string | Yes | Database containing the target table |
 | `table` | string | Yes | Table to ingest the query result into |
 | `mode` | string | No | set \(create, fail if it exists\), append \(add to an existing table\), set-or-append \(default\), or set-or-replace \(replace all data\) |
-| `sourceQuery` | string | Yes | KQL query whose result becomes the ingested data \(e.g., LogsTable \| where Level == "Error" \| where Timestamp > ago\(1h\)\) |
+| `sourceQuery` | string | Yes | KQL query whose result becomes the ingested data \(e.g., LogsTable \| where Level == "Error" \| where Timestamp > ago\(1h\)\). Project the columns in the target table\'s order — matching is positional, not by name |
 | `async` | boolean | No | Return immediately with an OperationId and keep ingesting in the background. Check progress with Show Operations |
 | `ingestionProperties` | string | No | Optional ingestion properties clause contents, e.g. distributed=true, tags=\"\[''daily''\]\" |
 

apps/docs/content/docs/en/integrations/table.mdx

@@ -226,6 +226,7 @@ Query rows from a table with filtering, sorting, and pagination
 | `totalCount` | number | Total rows matching filter |
 | `limit` | number | Limit used in query |
 | `offset` | number | Offset used in query |
+| `nextCursor` | string | Non-null when more rows match past this page. A page can end early at the byte budget, so this — not a short rowCount — is what says whether more remain. To page, advance offset by rowCount and stop when this is null. |
 
 ### Get Row
 

apps/sim/blocks/blocks/azure_data_explorer.ts

@@ -90,6 +90,19 @@ Examples:
 
 Return ONLY the schema - no explanations, no parentheses, no markdown fences.`
 
+/**
+ * Kusto matches an ingested query result to the target table positionally, by
+ * column type — never by column name — so the prompt has to make column order
+ * explicit or the generated query quietly fills the wrong columns.
+ */
+const INGEST_QUERY_WAND_PROMPT = `${KQL_WAND_PROMPT.replace('Return ONLY the KQL query - no explanations, no markdown fences.', '')}
+This query's result is ingested into an existing table. Kusto matches columns by
+position and type, NOT by name, so the projected columns must come out in the
+target table's column order. Use an explicit \`project\` listing the columns in
+that order as the final operator.
+
+Return ONLY the KQL query - no explanations, no markdown fences.`
+
 /** Switch and dropdown values arrive as booleans or their string form. */
 function toBoolean(value: unknown): true | undefined {
   return value === true || value === 'true' ? true : undefined
@@ -303,7 +316,7 @@ export const AzureDataExplorerBlock: BlockConfig<AzureDataExplorerTableResponse>
       required: { field: 'operation', value: 'azure_data_explorer_ingest_from_query' },
       wandConfig: {
         enabled: true,
-        prompt: KQL_WAND_PROMPT,
+        prompt: INGEST_QUERY_WAND_PROMPT,
         placeholder: 'Describe the rows you want to materialize into the table',
       },
     },
@@ -625,7 +638,7 @@ export const AzureDataExplorerBlockMeta = {
       description:
         'Build or refresh a summary table in Azure Data Explorer from a query over raw data.',
       content:
-        '# Materialize A Rollup Table\n\nTurn an expensive query over raw telemetry into a small table that is cheap to read.\n\n## Steps\n1. Run Show Table Details on the source table to see how much data the query will scan.\n2. Write the aggregating KQL — `summarize` the raw rows into the shape you want, bucketing time with `bin()` where relevant.\n3. Run Ingest From Query against the target table. Use `set-or-append` to add the new window to an existing rollup, `set-or-replace` to rebuild it from scratch, and `set` only for the first run.\n4. For a large backfill, enable the background option and poll Show Operations with the returned operation ID until the state is Completed.\n5. Run Query against the rollup to confirm the row count and time range look right.\n\n## Output\nReport the target table, the mode used, the rows or extents produced, and the verification query result. Call out that `set-or-replace` discards the existing data in the table.',
+        '# Materialize A Rollup Table\n\nTurn an expensive query over raw telemetry into a small table that is cheap to read.\n\n## Steps\n1. Run Show Table Details on the source table to see how much data the query will scan.\n2. Run Show Table Schema on the **target** table. Kusto matches an ingested query result to the table by column position and type, never by name, so you need its exact column order before writing the query.\n3. Write the aggregating KQL — `summarize` the raw rows into the shape you want, bucketing time with `bin()` where relevant — and end it with an explicit `project` listing the columns in the target table order.\n4. Run Ingest From Query against the target table. Use `set-or-append` to add the new window to an existing rollup, `set-or-replace` to rebuild it from scratch, and `set` only for the first run.\n5. For a large backfill, enable the background option and poll Show Operations with the returned operation ID until the state is Completed.\n6. Run Query against the rollup and spot-check a few rows to confirm each column holds what it should, not just that the row count is plausible.\n\n## Output\nReport the target table, the mode used, the rows or extents produced, and the verification query result. Call out that `set-or-replace` discards the existing data in the table, and that a mismatched column order corrupts data silently rather than failing.',
     },
     {
       name: 'debug-ingestion-failures',

apps/sim/lib/integrations/integrations.json

@@ -2261,7 +2261,7 @@
         },
         {
           "name": "Ingest From Query",
-          "description": "Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow."
+          "description": "Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow. Kusto matches the query result to the target table by column type and position, NOT by column name, so project the columns in exactly the table's order or the data lands in the wrong columns."
         },
         {
           "name": "Create Table",

apps/sim/tools/azure_data_explorer/ingest_from_query.ts

@@ -19,7 +19,7 @@ export const azureDataExplorerIngestFromQueryTool: ToolConfig<
   id: 'azure_data_explorer_ingest_from_query',
   name: 'Azure Data Explorer Ingest From Query',
   description:
-    'Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow.',
+    "Materialize the result of a KQL query into a table with .set, .append, .set-or-append, or .set-or-replace. Use this to build rollup or summary tables instead of pushing rows from a workflow. Kusto matches the query result to the target table by column type and position, NOT by column name, so project the columns in exactly the table's order or the data lands in the wrong columns.",
   version: '1.0.0',
   params: {
     clusterUri: {
@@ -76,7 +76,7 @@ export const azureDataExplorerIngestFromQueryTool: ToolConfig<
       required: true,
       visibility: 'user-or-llm',
       description:
-        'KQL query whose result becomes the ingested data (e.g., LogsTable | where Level == "Error" | where Timestamp > ago(1h))',
+        'KQL query whose result becomes the ingested data (e.g., LogsTable | where Level == "Error" | where Timestamp > ago(1h)). Project the columns in the target table\'s order — matching is positional, not by name',
     },
     async: {
       type: 'boolean',