@databricks/appkit-ui 0.33.0 → 0.34.0

package/docs/api/appkit/Variable.sql.md

@@ -2,10 +2,25 @@
 
 ```ts
 const sql: {
+  bigint: SQLNumberMarker & {
+     __sql_type: "BIGINT";
+  };
   binary: SQLBinaryMarker;
   boolean: SQLBooleanMarker;
   date: SQLDateMarker;
+  double: SQLNumberMarker & {
+     __sql_type: "DOUBLE";
+  };
+  float: SQLNumberMarker & {
+     __sql_type: "FLOAT";
+  };
+  int: SQLNumberMarker & {
+     __sql_type: "INT";
+  };
   number: SQLNumberMarker;
+  numeric: SQLNumberMarker & {
+     __sql_type: "NUMERIC";
+  };
   string: SQLStringMarker;
   timestamp: SQLTimestampMarker;
 };
@@ -16,6 +31,40 @@ SQL helper namespace
 
 ## Type Declaration[​](#type-declaration "Direct link to Type Declaration")
 
+### bigint()[​](#bigint "Direct link to bigint()")
+
+```ts
+bigint(value: string | number | bigint): SQLNumberMarker & {
+  __sql_type: "BIGINT";
+};
+
+```
+
+Creates a `BIGINT` (64-bit signed integer) parameter. Accepts JS `bigint` so callers can round-trip values outside `Number.MAX_SAFE_INTEGER` without precision loss; for `number` inputs, requires `Number.isSafeInteger(value)`.
+
+Rejects values outside the signed 64-bit range `[-2^63, 2^63 - 1]`.
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                             | Description                                      |
+| --------- | -------------------------------- | ------------------------------------------------ |
+| `value`   | `string` \| `number` \| `bigint` | Integer number, bigint, or integer-shaped string |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`SQLNumberMarker` & { `__sql_type`: `"BIGINT"`; }
+
+Marker pinned to `BIGINT`
+
+#### Example[​](#example "Direct link to Example")
+
+```typescript
+sql.bigint(42);                     // { __sql_type: "BIGINT", value: "42" }
+sql.bigint(9007199254740993n);      // { __sql_type: "BIGINT", value: "9007199254740993" }
+sql.bigint("9007199254740993");     // { __sql_type: "BIGINT", value: "9007199254740993" }
+
+```
+
 ### binary()[​](#binary "Direct link to binary()")
 
 ```ts
@@ -25,13 +74,13 @@ binary(value: string | Uint8Array | ArrayBuffer): SQLBinaryMarker;
 
 Creates a BINARY parameter as hex-encoded STRING Accepts Uint8Array, ArrayBuffer, or hex string Note: Databricks SQL Warehouse doesn't support BINARY as parameter type, so this helper returns a STRING with hex encoding. Use UNHEX(<!-- -->:param<!-- -->) in your SQL.
 
-#### Parameters[​](#parameters "Direct link to Parameters")
+#### Parameters[​](#parameters-1 "Direct link to Parameters")
 
 | Parameter | Type                                      | Description                            |
 | --------- | ----------------------------------------- | -------------------------------------- |
 | `value`   | `string` \| `Uint8Array` \| `ArrayBuffer` | Uint8Array, ArrayBuffer, or hex string |
 
-#### Returns[​](#returns "Direct link to Returns")
+#### Returns[​](#returns-1 "Direct link to Returns")
 
 `SQLBinaryMarker`
 
@@ -63,13 +112,13 @@ boolean(value: string | number | boolean): SQLBooleanMarker;
 
 Create a BOOLEAN type parameter Accepts booleans, strings, or numbers
 
-#### Parameters[​](#parameters-1 "Direct link to Parameters")
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
 
 | Parameter | Type                              | Description                |
 | --------- | --------------------------------- | -------------------------- |
 | `value`   | `string` \| `number` \| `boolean` | Boolean, string, or number |
 
-#### Returns[​](#returns-1 "Direct link to Returns")
+#### Returns[​](#returns-2 "Direct link to Returns")
 
 `SQLBooleanMarker`
 
@@ -116,13 +165,13 @@ date(value: string | Date): SQLDateMarker;
 
 Creates a DATE type parameter Accepts Date objects or ISO date strings (YYYY-MM-DD format)
 
-#### Parameters[​](#parameters-2 "Direct link to Parameters")
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
 
 | Parameter | Type               | Description                    |
 | --------- | ------------------ | ------------------------------ |
 | `value`   | `string` \| `Date` | Date object or ISO date string |
 
-#### Returns[​](#returns-2 "Direct link to Returns")
+#### Returns[​](#returns-3 "Direct link to Returns")
 
 `SQLDateMarker`
 
@@ -142,6 +191,99 @@ params = { startDate: "2024-01-01" }
 
 ```
 
+### double()[​](#double "Direct link to double()")
+
+```ts
+double(value: string | number): SQLNumberMarker & {
+  __sql_type: "DOUBLE";
+};
+
+```
+
+Creates a `DOUBLE` (double-precision, 64-bit) parameter. Same precision as a JS `number`, so `sql.double(value)` is exact for any JS number.
+
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
+
+| Parameter | Type                 | Description              |
+| --------- | -------------------- | ------------------------ |
+| `value`   | `string` \| `number` | Number or numeric string |
+
+#### Returns[​](#returns-4 "Direct link to Returns")
+
+`SQLNumberMarker` & { `__sql_type`: `"DOUBLE"`; }
+
+Marker pinned to `DOUBLE`
+
+#### Example[​](#example-1 "Direct link to Example")
+
+```typescript
+sql.double(3.14);   // { __sql_type: "DOUBLE", value: "3.14" }
+
+```
+
+### float()[​](#float "Direct link to float()")
+
+```ts
+float(value: string | number): SQLNumberMarker & {
+  __sql_type: "FLOAT";
+};
+
+```
+
+Creates a `FLOAT` (single-precision, 32-bit) parameter. Note that JS numbers are 64-bit doubles, so values may be rounded to fit FLOAT precision at bind time.
+
+#### Parameters[​](#parameters-5 "Direct link to Parameters")
+
+| Parameter | Type                 | Description              |
+| --------- | -------------------- | ------------------------ |
+| `value`   | `string` \| `number` | Number or numeric string |
+
+#### Returns[​](#returns-5 "Direct link to Returns")
+
+`SQLNumberMarker` & { `__sql_type`: `"FLOAT"`; }
+
+Marker pinned to `FLOAT`
+
+#### Example[​](#example-2 "Direct link to Example")
+
+```typescript
+sql.float(3.14);   // { __sql_type: "FLOAT", value: "3.14" }
+
+```
+
+### int()[​](#int "Direct link to int()")
+
+```ts
+int(value: string | number): SQLNumberMarker & {
+  __sql_type: "INT";
+};
+
+```
+
+Creates an `INT` (32-bit signed integer) parameter. Use when the column or context requires `INT` specifically (e.g. legacy schemas, or to make the wire type explicit).
+
+Rejects non-integers, values outside `Number.MAX_SAFE_INTEGER` (for number inputs), and values outside the signed 32-bit range `[-2^31, 2^31 - 1]`.
+
+#### Parameters[​](#parameters-6 "Direct link to Parameters")
+
+| Parameter | Type                 | Description                             |
+| --------- | -------------------- | --------------------------------------- |
+| `value`   | `string` \| `number` | Integer number or integer-shaped string |
+
+#### Returns[​](#returns-6 "Direct link to Returns")
+
+`SQLNumberMarker` & { `__sql_type`: `"INT"`; }
+
+Marker pinned to `INT`
+
+#### Example[​](#example-3 "Direct link to Example")
+
+```typescript
+sql.int(42);     // { __sql_type: "INT", value: "42" }
+sql.int("42");   // { __sql_type: "INT", value: "42" }
+
+```
+
 ### number()[​](#number "Direct link to number()")
 
 ```ts
@@ -149,31 +291,71 @@ number(value: string | number): SQLNumberMarker;
 
 ```
 
-Creates a NUMERIC type parameter Accepts numbers or numeric strings
+Creates a numeric type parameter. The wire SQL type is inferred from the value so the parameter binds correctly in any context, including `LIMIT` and `OFFSET`:
 
-#### Parameters[​](#parameters-3 "Direct link to Parameters")
+* JS integer in `[-2^31, 2^31 - 1]` → `INT`
+* JS integer outside `INT` but within `Number.MAX_SAFE_INTEGER` → `BIGINT`
+* JS non-integer (`3.14`) → `DOUBLE`
+* integer-shaped string in `INT` range → `INT` (common HTTP-input case)
+* integer-shaped string outside `INT` but within `BIGINT` → `BIGINT`
+* decimal-shaped string (`"123.45"`) → `NUMERIC` (preserves precision)
+
+Why default to `INT`? Spark's `LIMIT` and `OFFSET` operators require `IntegerType` specifically — `BIGINT` (`LongType`) is rejected with `INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`. Catalyst auto-widens `INT` to `BIGINT` / `DECIMAL` / `DOUBLE` for wider columns, so `INT` is a strictly better default than `BIGINT`.
+
+Throws on `NaN`, `Infinity`, JS integers outside `Number.MAX_SAFE_INTEGER`, integer-shaped strings outside the `BIGINT` range, or non-numeric strings. Reach for `sql.int()`, `sql.bigint()`, `sql.float()`, `sql.double()`, or `sql.numeric()` to override the inferred type.
+
+#### Parameters[​](#parameters-7 "Direct link to Parameters")
 
 | Parameter | Type                 | Description              |
 | --------- | -------------------- | ------------------------ |
 | `value`   | `string` \| `number` | Number or numeric string |
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `SQLNumberMarker`
 
-Marker object for NUMERIC type parameter
+Marker for a numeric SQL parameter
 
-#### Examples[​](#examples-3 "Direct link to Examples")
+#### Example[​](#example-4 "Direct link to Example")
 
 ```typescript
-const params = { userId: sql.number(123) };
-params = { userId: "123" }
+sql.number(123);              // { __sql_type: "INT",    value: "123" }
+sql.number(3_000_000_000);    // { __sql_type: "BIGINT", value: "3000000000" }
+sql.number(0.5);              // { __sql_type: "DOUBLE", value: "0.5" }
+sql.number("10");             // { __sql_type: "INT",    value: "10" }
+sql.number("123.45");         // { __sql_type: "NUMERIC", value: "123.45" }
+
+```
+
+### numeric()[​](#numeric "Direct link to numeric()")
+
+```ts
+numeric(value: string | number): SQLNumberMarker & {
+  __sql_type: "NUMERIC";
+};
 
 ```
 
+Creates a `NUMERIC` (fixed-point DECIMAL) parameter. Use when you need exact decimal arithmetic (currency, percentages) — pass values as strings to avoid JS-number precision loss.
+
+Note: passing a JS `number` is accepted but lossy for many values (e.g. `0.1 + 0.2` → `"0.30000000000000004"`). Prefer strings.
+
+#### Parameters[​](#parameters-8 "Direct link to Parameters")
+
+| Parameter | Type                 | Description                                                |
+| --------- | -------------------- | ---------------------------------------------------------- |
+| `value`   | `string` \| `number` | Number or numeric string (strings preferred for precision) |
+
+#### Returns[​](#returns-8 "Direct link to Returns")
+
+`SQLNumberMarker` & { `__sql_type`: `"NUMERIC"`; }
+
+Marker pinned to `NUMERIC`
+
+#### Example[​](#example-5 "Direct link to Example")
+
 ```typescript
-const params = { userId: sql.number("123") };
-params = { userId: "123" }
+sql.numeric("12345.6789");   // { __sql_type: "NUMERIC", value: "12345.6789" }
 
 ```
 
@@ -186,19 +368,19 @@ string(value: string | number | boolean): SQLStringMarker;
 
 Creates a STRING type parameter Accepts strings, numbers, or booleans
 
-#### Parameters[​](#parameters-4 "Direct link to Parameters")
+#### Parameters[​](#parameters-9 "Direct link to Parameters")
 
 | Parameter | Type                              | Description                |
 | --------- | --------------------------------- | -------------------------- |
 | `value`   | `string` \| `number` \| `boolean` | String, number, or boolean |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-9 "Direct link to Returns")
 
 `SQLStringMarker`
 
 Marker object for STRING type parameter
 
-#### Examples[​](#examples-4 "Direct link to Examples")
+#### Examples[​](#examples-3 "Direct link to Examples")
 
 ```typescript
 const params = { name: sql.string("John") };
@@ -227,19 +409,19 @@ timestamp(value: string | number | Date): SQLTimestampMarker;
 
 Creates a TIMESTAMP type parameter Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers
 
-#### Parameters[​](#parameters-5 "Direct link to Parameters")
+#### Parameters[​](#parameters-10 "Direct link to Parameters")
 
 | Parameter | Type                           | Description                                                 |
 | --------- | ------------------------------ | ----------------------------------------------------------- |
 | `value`   | `string` \| `number` \| `Date` | Date object, ISO timestamp string, or Unix timestamp number |
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-10 "Direct link to Returns")
 
 `SQLTimestampMarker`
 
 Marker object for TIMESTAMP type parameter
 
-#### Examples[​](#examples-5 "Direct link to Examples")
+#### Examples[​](#examples-4 "Direct link to Examples")
 
 ```typescript
 const params = { createdTime: sql.timestamp(new Date("2024-01-01T12:00:00Z")) };

package/docs/app-management.md

@@ -59,10 +59,10 @@ databricks apps deploy --help
 
   ```
 
-* Skip the build step for faster iteration:
+* Skip validation for faster iteration:
 
   ```bash
-  databricks apps deploy --skip-build
+  databricks apps deploy --skip-validation
 
   ```
 

package/docs/plugins/analytics.md

@@ -40,16 +40,21 @@ Use `:paramName` placeholders and optionally annotate parameter types using SQL
 ```sql
 -- @param startDate DATE
 -- @param endDate DATE
--- @param limit NUMERIC
+-- @param limit INT
 SELECT ...
 WHERE usage_date BETWEEN :startDate AND :endDate
 LIMIT :limit
 
 ```
 
+`LIMIT` / `OFFSET` require Spark `IntegerType` specifically — `BIGINT` (`LongType`) is rejected with `INVALID_LIMIT_LIKE_EXPRESSION.DATA_TYPE`. Annotate with `INT`, or use `sql.number()` (auto-infers `INT` for values in `[-2^31, 2^31-1]`, falling back to `BIGINT` for wider values) / `sql.int()` at the call site.
+
 **Supported `-- @param` types** (case-insensitive):
 
-* `STRING`, `NUMERIC`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`
+* `STRING`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`
+* `INT`, `BIGINT`, `TINYINT`, `SMALLINT` — bind via `sql.int()` / `sql.bigint()`
+* `FLOAT`, `DOUBLE` — bind via `sql.float()` / `sql.double()`
+* `NUMERIC`, `DECIMAL` — bind via `sql.numeric()` (pass strings for precision)
 
 ## Server-injected parameters[​](#server-injected-parameters "Direct link to Server-injected parameters")
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",