@celigo/api-specs 0.2.109 → 0.2.110

package/dist/storagequery.yml

@@ -44,13 +44,16 @@ paths:
 
         Everything that can be checked before running is checked here and answered
         synchronously, and a rejected submit creates no job: the statement must parse, be
-        exactly one `SELECT`, use only allow-listed functions, reference files only through
+        exactly one `SELECT` (a `DESCRIBE <query>` or `SUMMARIZE <query>` over a storage
+        file is accepted as well and returns the column or summary rows), use only
+        allow-listed functions, reference files only through
         bare storage paths or the storage reader functions, and every path must resolve to
         a file — or a folder of same-format files — the caller can read. A statement that
         references no file is accepted only when it is a pure constant expression. Supported
         file formats are CSV/TSV, JSON, NDJSON/JSONL, and Parquet; the reader is chosen from
         the file's extension (or its MIME type), and an explicit reader function must match
-        it.
+        it. A folder is referenced with a trailing slash and contributes its direct child
+        files only; wildcard paths are not supported.
 
         Read options are named arguments of the reader call, checked against a per-reader
         allowlist — for `read_csv`/`read_csv_auto`: `header`, `delim`, `quote`, `escape`,
@@ -186,9 +189,11 @@ paths:
             file's format (`STORAGE_QUERY_READER_FORMAT_MISMATCH`); a row generator with no
             file reference (`STORAGE_QUERY_NO_STORAGE_REFERENCE`) or one that would generate
             more rows than allowed (`STORAGE_QUERY_GENERATOR_TOO_LARGE`); a schema- or
-            catalog-qualified table name (`STORAGE_QUERY_INVALID_SOURCE`); an unsupported
-            file type (`STORAGE_QUERY_UNSUPPORTED_FILE_TYPE`); a folder that is empty, mixes
-            formats, or holds too many files (`STORAGE_QUERY_FOLDER_EMPTY`,
+            catalog-qualified table name, or a path carrying a wildcard
+            (`STORAGE_QUERY_INVALID_SOURCE`); a folder path without its trailing slash
+            (`STORAGE_NOT_A_FILE`) or a file path with one (`STORAGE_ITEM_NOT_FOLDER`); an
+            unsupported file type (`STORAGE_QUERY_UNSUPPORTED_FILE_TYPE`); a folder that is
+            empty, mixes formats, or holds too many files (`STORAGE_QUERY_FOLDER_EMPTY`,
             `STORAGE_QUERY_MIXED_FORMAT_FOLDER`, `STORAGE_QUERY_FOLDER_TOO_MANY_FILES`); too
             many distinct files (`STORAGE_QUERY_TOO_MANY_SOURCES`); or more input bytes than
             the cap (`STORAGE_QUERY_INPUT_TOO_LARGE`).
@@ -233,6 +238,18 @@ paths:
                     errors:
                       - code: STORAGE_QUERY_NO_STORAGE_REFERENCE
                         message: A query that generates rows must read at least one Celigo Storage file; only constant expressions may omit a file reference
+                wildcardPath:
+                  summary: Wildcard in a storage path
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_INVALID_SOURCE
+                        message: FROM target "orders/2026/*.csv" is not a valid Celigo Storage file path
+                folderWithoutSlash:
+                  summary: Folder path missing its trailing slash
+                  value:
+                    errors:
+                      - code: STORAGE_NOT_A_FILE
+                        message: Storage item "orders/2026" is not a file
         '429':
           description: |-
             Too many submits for this account in the current window
@@ -404,9 +421,12 @@ paths:
       description: |-
         Returns one page of a completed job's rows. Pages run from 1 to the job's
         `pageCount`; omit `page` for the first one and keep requesting `page + 1` while
-        `hasMore` is true. A completed job that matched nothing has `pageCount` 0 and still
-        serves page 1 as an empty page, so an empty result set never looks like a bad
-        request. Rows exist only for a `completed` job: a `queued` or `running` job answers
+        `hasMore` is true. A page holds as many whole rows as fit the service's page size,
+        which is a byte budget rather than a row count — a result of several hundred
+        thousand small rows can arrive as a single page — and no parameter changes it, so a
+        caller that must hold a page in memory bounds the result with `LIMIT` in the
+        statement. A completed job that matched nothing has `pageCount` 0 and still serves
+        page 1 as an empty page, so an empty result set never looks like a bad request. Rows exist only for a `completed` job: a `queued` or `running` job answers
         409 until it finishes, and a `failed` job answers 409 permanently — read its `error`
         from the status route instead. Jobs are scoped to the submitting account, and an
         expired job answers 404. Requires the account's license to include the Storage
@@ -565,21 +585,34 @@ components:
           description: |-
             A single `SELECT` statement. Storage files are its tables: write a file or
             folder path where a table name would go, quoted as an identifier
-            (`FROM "orders/2026/september.csv"`), or pass the path as the first, literal
-            argument of a reader function (`read_csv_auto`, `read_csv`, `read_json_auto`,
-            `read_json`, `read_ndjson_auto`, `read_ndjson`, `read_parquet`) when the file
-            needs explicit read options. Paths are relative to the account's storage root.
-            Anything other than one `SELECT` — an `UPDATE`, two statements, a table function
-            that is not a storage reader, or a function outside the allowlist — is rejected
-            at submit with a 4xx and creates no job. A statement that references no file is
-            accepted only when it is a pure constant expression.
+            (`FROM "orders/2026/september.csv"`) or as a string literal, or pass the path as
+            the first, literal argument of a reader function (`read_csv_auto`, `read_csv`,
+            `read_json_auto`, `read_json`, `read_ndjson_auto`, `read_ndjson`, `read_parquet`)
+            when the file needs explicit read options. Paths are relative to the account's
+            storage root and case-sensitive; a leading `/` is accepted. A folder is
+            referenced with a trailing `/` (`FROM "orders/2026/"`) and reads its direct
+            child files — not its subfolders — as one table; a folder path without the
+            slash is refused at submit with 422 `STORAGE_NOT_A_FILE`, a file path with one
+            with 422 `STORAGE_ITEM_NOT_FOLDER`. Wildcards are not supported: a `*` or `?`
+            in a path answers 422 `STORAGE_QUERY_INVALID_SOURCE`. Anything other than one
+            `SELECT` — an `UPDATE`, two statements, a table function that is not a storage
+            reader, or a function outside the allowlist — is rejected at submit with a 4xx
+            and creates no job; `DESCRIBE <query>` and `SUMMARIZE <query>` are accepted and
+            run as ordinary jobs. A statement that references no file is accepted only when
+            it is a pure constant expression.
           examples:
             - SELECT customer_id, SUM(total) AS spend FROM "orders/2026/september.csv" GROUP BY customer_id ORDER BY spend DESC LIMIT 100
+            - SELECT status, COUNT(*) AS orders FROM "orders/2026/" GROUP BY status
       x-celigo-ai-guidance:
         - |-
           Quote storage paths as identifiers relative to the account root: FROM
           "folder/file.csv". A path that does not resolve fails the submit with 404
           STORAGE_QUERY_SOURCE_NOT_FOUND and the response carries no jobId.
+        - |-
+          End a folder path with a slash — FROM "folder/" — to read its direct child files
+          as one table; "folder" without the slash fails the submit with 422
+          STORAGE_NOT_A_FILE. Never write a wildcard such as "folder/*.csv": it fails with
+          422 STORAGE_QUERY_INVALID_SOURCE.
         - |-
           Put read options inside the SQL as named arguments of the reader call, e.g.
           read_csv_auto('folder/file.csv', header = true, delim = ';'). An option the reader
@@ -815,9 +848,19 @@ components:
           type: array
           description: |-
             Rows on this page, in the statement's output order. Each row is an object keyed
-            by column name (see `columns` on the job's status). Integer and boolean columns
-            arrive as JSON numbers and booleans; `DECIMAL` values arrive as strings so no
-            precision is lost. Empty on an empty result set.
+            by column name (see `columns` on the job's status). `TINYINT`, `SMALLINT`,
+            `INTEGER`, `FLOAT`, `DOUBLE` and `BOOLEAN` values arrive as JSON numbers and
+            booleans. `BIGINT`, `UBIGINT`, `HUGEINT` and `DECIMAL` values arrive as strings so
+            no precision is lost (`"9007199254740993"`, `"1.50"`) — and every whole-number
+            column inferred from a CSV, JSON or NDJSON file is `BIGINT`, as are `COUNT`, `SUM`
+            over integer columns and the ranking window functions, so those come back as
+            strings such as `"40"`. `DATE`, `TIME` and `TIMESTAMP` values arrive as strings
+            (`2026-09-01`, `10:00:00`, `2026-09-01 10:00:00`). A list column (`INTEGER[]`,
+            `VARCHAR[]` — including a JSON array the reader typed as a list) arrives as a JSON
+            array, a `STRUCT` as a JSON object, a `MAP` as an array of `{"key", "value"}`
+            pairs, an `INTERVAL` as `{"months", "days", "micros"}` where `months` and `days`
+            are numbers and `micros` is a string (`{"months": 0, "days": 1, "micros": "0"}`
+            for `INTERVAL 1 DAY`). Empty on an empty result set.
           items:
             type: object
             additionalProperties: true
@@ -826,6 +869,33 @@ components:
                 letter: a
                 num: '2.5'
                 flag: true
+            - - customer_id: C001
+                orders: '7'
+                spend: 1840.5
+            - - h: '170141183460469231731687303715884105727'
+                l:
+                  - 1
+                  - 2
+                  - 3
+                s:
+                  a: 1
+                  b: x
+                tm: '10:00:00'
+                iv:
+                  months: 0
+                  days: 1
+                  micros: '0'
+          x-celigo-ai-guidance:
+            - |-
+              Read the type from columns on the job's status before using a value: a
+              COUNT(*) or SUM over an integer column is BIGINT and arrives as the string
+              "40", not the number 40. When the consumer needs a JSON number, cast in the
+              statement — COUNT(*)::DOUBLE and COUNT(*)::INTEGER both arrive as the number
+              40. A cast to INTEGER fails the job when the BIGINT value is outside the
+              32-bit range: `SELECT 2147483648::INTEGER` fails with
+              STORAGE_QUERY_EXECUTION_FAILED ("Type INT64 with value 2147483648 can't be
+              cast because the value is out of range for the destination type INT32"), so
+              prefer DOUBLE for counts and sums whose size is unknown.
   responses:
     401-unauthorized:
       description: |-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.109",
+  "version": "0.2.110",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "9dfc0b9c",
+		"iasCommit": "155f6181",
 		"generatedAt": "2026-10-14"
 	},
 	"roots": {