@lark-base-open/base-database-cli 1.1.1 → 1.3.8

package/skills/lark-base-database/references/base-sql-errors.generated.md

@@ -0,0 +1,403 @@
+<!-- Generated by errorcatalog-gen; do not edit. -->
+# Unsupported SQL and alternatives
+
+Use names and types from catalog.json. Refresh the Catalog when the schema changes. Follow every precondition below; a guard intentionally changes error behavior. Outside-SQL policies use the following guidance: Compute it in the code that consumes the query result (in Base Site: a Page or an Edge Function).
+
+## Verified SQL forms
+
+### Division with a zero divisor
+
+Use NULLIF(divisor, 0) as the divisor if a NULL result is acceptable.
+
+Preconditions: The caller accepts NULL instead of a division-by-zero error.
+
+Validation kind: `guard`. Error code: `SQL_DIVISION_BY_ZERO`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, 1::bigint / NULLIF(0::bigint, 0::bigint) AS value FROM source ORDER BY id;
+```
+
+### Division with a nonzero divisor
+
+Use NULLIF(divisor, 0) as the divisor if a NULL result is acceptable.
+
+Preconditions: For a nonzero divisor the value must be unchanged.
+
+Validation kind: `guard`. Error code: `SQL_DIVISION_BY_ZERO`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, 7::bigint / NULLIF(2::bigint, 0::bigint) AS value FROM source ORDER BY id;
+```
+
+### Filter a window output in a subquery
+
+Compute the window in a SELECT subquery, then refer to its output.
+
+Preconditions: Move the window output into a subquery before filtering; this corrects an invalid window context.
+
+Validation kind: `author`. Error code: `SQL_WINDOW_NOT_ALLOWED`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders), ranked AS (SELECT id, ROW_NUMBER() OVER (ORDER BY sort_key, id) AS rn FROM source) SELECT id FROM ranked WHERE rn = 1 ORDER BY id;
+```
+
+### Use the PostgreSQL TO_CHAR spelling
+
+Use the stated public SQL function and its documented signature.
+
+Preconditions: Choose the intended PostgreSQL format; this example uses the full date and time format.
+
+Validation kind: `author`. Error code: `SQL_UNSUPPORTED_SYNTAX`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, TO_CHAR(TIMESTAMP '2026-09-26 12:34:56', 'YYYY-MM-DD HH24:MI:SS') AS value FROM source ORDER BY id;
+```
+
+### Give NULL an explicit public type
+
+Use an explicit CAST with the intended public SQL type.
+
+Preconditions: Choose the intended public type; the example chooses TEXT.
+
+Validation kind: `author`. Error code: `SQL_UNTYPED_NULL`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, CAST(NULL AS TEXT) AS value FROM source ORDER BY id;
+```
+
+### Correlated max join
+
+For an equality comparison to a grouped MAX, aggregate by the correlation key in a subquery and JOIN that result. Preserve NULL and empty-group behavior. Other correlated forms have no verified SQL rewrite.
+
+Preconditions: Equality to a correlated MAX grouped by the correlation key; preserve NULL keys and empty groups.
+
+Validation kind: `equivalent`. Error code: `SQL_UNSUPPORTED_SYNTAX`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT s.id, s.value FROM source s JOIN (SELECT group_key AS k, MAX(value) AS m FROM source GROUP BY group_key) g ON s.group_key = g.k WHERE s.value = g.m ORDER BY s.id;
+```
+
+### Octet length bytes
+
+STRLEN is not supported. For byte counts, use OCTET_LENGTH(text). Byte counts and character counts can differ; character counting has no verified SQL equivalent.
+
+Preconditions: The intent is byte count, not character count. The fixture includes non-ASCII text and NULL values.
+
+Validation kind: `equivalent`. Error code: `SQL_FUNCTION_NOT_FOUND`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, OCTET_LENGTH(text_value) AS value FROM source ORDER BY id;
+```
+
+### Array scalar containment
+
+Both operands must be arrays of compatible element types. For single-value containment, wrap the scalar in a one-element array.
+
+Preconditions: Single-value array containment is intended; include NULL input and unmatched elements.
+
+Validation kind: `equivalent`. Error code: `SQL_OPERATOR_TYPE_MISMATCH`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, ARRAY[group_key] <@ ARRAY['g1','g2'] AS value FROM source ORDER BY id;
+```
+
+### Array scalar contains
+
+Both operands must be arrays of compatible element types. For single-value containment, wrap the scalar in a one-element array.
+
+Preconditions: Single-value array containment is intended; include NULL input and unmatched elements.
+
+Validation kind: `equivalent`. Error code: `SQL_OPERATOR_TYPE_MISMATCH`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, ARRAY['g1','g2'] @> ARRAY[group_key] AS value FROM source ORDER BY id;
+```
+
+### Numeric predicate
+
+Use a BOOL condition. If the intent is to exclude zero, compare the numeric expression with zero; NULL rows will not match.
+
+Preconditions: The explicitly selected intent is to exclude numeric zero and NULL.
+
+Validation kind: `author`. Error code: `SQL_WHERE_TYPE_MISMATCH`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id FROM source WHERE value <> 0 ORDER BY id;
+```
+
+### Text predicate
+
+Use a BOOL condition. If the intent is to exclude empty text, compare the text expression with an empty string; NULL rows will not match.
+
+Preconditions: The explicitly selected intent is to exclude empty text and NULL.
+
+Validation kind: `author`. Error code: `SQL_WHERE_TYPE_MISMATCH`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id FROM source WHERE text_value <> '' ORDER BY id;
+```
+
+### Remainder nullif
+
+Use NULLIF(divisor, 0) as the remainder divisor if a NULL result is acceptable.
+
+Preconditions: Returning NULL instead of an error for a zero remainder divisor is acceptable.
+
+Validation kind: `guard`. Error code: `SQL_DIVISION_BY_ZERO`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, CAST(sort_key AS BIGINT) % NULLIF(CAST(0 AS BIGINT), CAST(0 AS BIGINT)) AS value FROM source ORDER BY id;
+```
+
+### Remainder nullif nonzero
+
+Use NULLIF(divisor, 0) as the remainder divisor if a NULL result is acceptable.
+
+Preconditions: Integer-valued sort keys; verify that the guard preserves a nonzero divisor.
+
+Validation kind: `guard`. Error code: `SQL_DIVISION_BY_ZERO`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT id, CAST(sort_key AS BIGINT) % NULLIF(CAST(2 AS BIGINT), CAST(0 AS BIGINT)) AS value FROM source ORDER BY id;
+```
+
+### Cast int format
+
+Use an optional sign and decimal digits for INT input, for example '123'. Supply the intended value; do not substitute the example.
+
+Preconditions: The caller explicitly supplies the value 123; this example must not replace an unknown intended value.
+
+Validation kind: `author`. Error code: `SQL_INVALID_CAST`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT CAST('123' AS INT) AS value FROM source LIMIT 1;
+```
+
+### Cast double format
+
+Use a finite decimal number for DOUBLE input, for example '1.25'. Supply the intended value; do not substitute the example.
+
+Preconditions: The caller explicitly supplies the finite decimal value 1.25.
+
+Validation kind: `author`. Error code: `SQL_INVALID_CAST`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+WITH source AS (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) SELECT CAST('1.25' AS DOUBLE PRECISION) AS value FROM source LIMIT 1;
+```
+
+### Materialize option names before array construction
+
+Compute OPTION.name in a derived table first, then construct ARRAY from that projected column. Preserve the original joins, filters, and NULL behavior.
+
+Preconditions: Project OPTION.name before constructing the array. This case preserves an INNER JOIN with condition TRUE, NULL values, duplicates and row count; retain other original predicates.
+
+Validation kind: `equivalent`. Error code: `SQL_UNSUPPORTED_SYNTAX`.
+
+The example uses an `orders` table with `group_key`, `sort_key`, `value`, and `text_value` columns. Replace these with exact Catalog names.
+
+```sql
+SELECT q.id, v AS value FROM (SELECT rec_id AS id, group_key, sort_key, value, text_value FROM orders) q CROSS JOIN UNNEST(ARRAY[q.text_value]) v ORDER BY q.id;
+```
+
+## Unsupported diagnostics
+
+Placeholders denote the names and types reported in the error. Use the concrete restriction reported in the error; placeholders do not declare every possible value unsupported.
+
+| Code / variant | Reason | Repair |
+|---|---|---|
+| `SQL_CAST_TYPE_MISMATCH` / `unsupported_conversion` | Conversion from {SourceType} to {TargetType} is not supported. | Choose a column or parameter already having the required type. An equivalent conversion has not been verified. [outside_sql] |
+| `SQL_FUNCTION_NOT_FOUND` / `known_unavailable` | Function {Function} is not supported. | {Alternative} [outside_sql] |
+| `SQL_FUNCTION_NOT_FOUND` / `unsupported_function` | Function {Function} is not supported. | [outside_sql] |
+| `SQL_INTERVAL_LITERAL_CALENDAR_UNIT_NOT_SUPPORTED` / `interval_calendar_unit` | Calendar interval unit {Unit} is not supported. | A fixed day count is not equivalent. [outside_sql] |
+| `SQL_INTERVAL_LITERAL_FRACTIONAL_MILLISECONDS` / `interval_precision` | The interval must be an exact whole number of milliseconds. | Whole milliseconds are supported; higher precision cannot be preserved by rounding. [outside_sql] |
+| `SQL_INTERVAL_LITERAL_UNIT_NOT_SUPPORTED` / `interval_unit` | Interval unit {Unit} is not supported. | Use day, hour, minute, second, or millisecond units. |
+| `SQL_UNSUPPORTED_COLUMN_TYPE` / `column_representation` | Column {Column} has type {BaseType}; {Representation}. | A supported column is required for an equivalent SQL operation. [outside_sql] |
+| `SQL_UNSUPPORTED_OPERATOR` / `unavailable_operation` | This {Operation} is not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_OPERATOR` / `unsupported_field_operator` | Column {Column} has type {ActualType}, which does not support {Operator}. | [outside_sql] |
+| `SQL_UNSUPPORTED_OPERATOR` / `unsupported_operator` | Operator {Operator} is not supported for {ArgTypes}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `aggregate_modifier` | Aggregate {Function} does not support {Modifier}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `aggregate_separator` | The separator of {Function} must be {Requirement}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `array_dimension` | ARRAY_LENGTH dimension must be {Form}. | Changing the dimension can change the result. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `array_subquery_shape` | This ARRAY subquery shape is not supported. | Only a direct single-column UNNEST projection is supported here. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `binary_operator` | Unsupported binary operator: {Operator}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `capability_budget` | The supported limit was exceeded: {Dimension}. | Reduce this query dimension or split the operation into separate queries. |
+| `SQL_UNSUPPORTED_SYNTAX` / `correlated_exists` | Correlated EXISTS does not support {Predicate}. | Only supported equality correlations can be expressed in SQL. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `correlated_option_array` | Correlated OPTION.name expressions inside ARRAY require a materialized input. | Compute OPTION.name in a derived table first, then construct ARRAY from that projected column. Preserve the original joins, filters, and NULL behavior. |
+| `SQL_UNSUPPORTED_SYNTAX` / `date_trunc_context` | DATE_TRUNC output cannot be used in {Context}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `date_trunc_unit` | DATE_TRUNC unit {Part} is not supported because it cannot preserve timestamp identity. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `function_input_types` | Function {Function} requires TEXT arguments; received {ArgTypes}. | Use TEXT inputs for this function. |
+| `SQL_UNSUPPORTED_SYNTAX` / `identity_operation` | Unsupported operation: {Constraint}. | Compare identities of the same kind or use separate TEXT parameters; do not transform identity values. |
+| `SQL_UNSUPPORTED_SYNTAX` / `identity_output` | Output {Output} combines identities with incompatible values. | Keep USER identities, CHAT identities, and plain text in separate outputs. |
+| `SQL_UNSUPPORTED_SYNTAX` / `identity_parameter` | Parameter {Parameter} violates this constraint: {Constraint}. | Use separate TEXT parameters for each identity namespace and for plain text. |
+| `SQL_UNSUPPORTED_SYNTAX` / `location_coordinate` | LOCATION member {Member} is not supported. | An address or complete object is not an equivalent result. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `named_window_reference` | Window definition {Window} is missing or duplicated. | Use a unique WINDOW definition and reference its declared name. |
+| `SQL_UNSUPPORTED_SYNTAX` / `nested_cte` | A nested CTE is not supported in {Context}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `null_ordering` | Explicit NULLS ordering requires {Constraint}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `option_member_context` | OPTION[].name cannot be used in {Context}. | An equivalent SQL rewrite preserving row multiplicity has not been verified. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `protocol_shape` | Invalid compiled structure: {Shape} is not supported. | Recompile the query using the current supported contract. |
+| `SQL_UNSUPPORTED_SYNTAX` / `route_table_required` | The query must reference a table for execution routing. | Adding an arbitrary table can change row count. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `subquery_constraint` | {Construct} requires {Constraint}. | The subquery must satisfy the stated constraint for a supported SQL rewrite. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `syntax_feature` | SQL feature {Feature} is not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `syntax_restriction` | {Restriction}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `type_representation` | The query cannot represent type {ActualType}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `unary_operator` | Unsupported unary operator: {Operator}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `unavailable_function_syntax` | Function {Function} is not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `window_capability` | Window function {Function} requires {Requirement}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_DISTINCT_FROM` / `distinct_comparison` | IS DISTINCT FROM and IS NOT DISTINCT FROM are not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_EXCEPT` / `except_set` | EXCEPT {Quantifier} is not supported. | Duplicate and NULL behavior must be preserved. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_INTERSECT` / `intersect_set` | INTERSECT {Quantifier} is not supported. | Duplicate and NULL behavior must be preserved. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_LAG_LEAD` / `lag_lead_argument` | Argument {Argument} of {Function} has an unsupported form; expected {Form}. | Argument {Argument} requires {Form}. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_LATERAL` / `lateral_correlation` | LATERAL with {Correlation} is not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_NULL_IN_LIST` / `null_in_list` | An explicit NULL element in an IN or NOT IN list is not supported. | Removing NULL can change the result. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_RECURSIVE_CTE` / `recursive_cte` | Recursive CTE {CTE} is not supported. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_REGEXP_REPLACE` / `regexp_replacement` | The requested replacement mode is not supported: {Mode}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX_WINDOW_FRAME` / `window_frame` | The window specification is not supported: {Frame}. | Changing the frame can change the result. [outside_sql] |
+
+## Syntax restriction repair policies
+
+| Restriction | Policy | Reason | Repair |
+|---|---|---|---|
+| `AggregateCallForm` | `outside_sql` | This aggregate FILTER, ORDER BY, WITHIN GROUP, or variadic call form is not supported | [outside_sql] |
+| `AggregateFilter` | `outside_sql` | FILTER requires an aggregate function | [outside_sql] |
+| `AnyKeyType` | `outside_sql` | Expanded ANY arrays require numeric or TEXT operands | [outside_sql] |
+| `ArrayConstructor` | `outside_sql` | This ANY operand requires an ARRAY constructor | [outside_sql] |
+| `ArrayDimension` | `outside_sql` | ARRAY_LENGTH requires literal 1 as the dimension | [outside_sql] |
+| `ArrayLengthArity` | `outside_sql` | Use ARRAY_LENGTH(array, 1) or CARDINALITY(array) | [outside_sql] |
+| `ArraySubquery` | `outside_sql` | ANY array operands and elements cannot contain subqueries | [outside_sql] |
+| `ArrayTypeModifier` | `outside_sql` | An empty ANY array requires an unmodified supported scalar array type | [outside_sql] |
+| `BetweenBounds` | `outside_sql` | BETWEEN requires two bounds | [outside_sql] |
+| `BooleanOperands` | `outside_sql` | A boolean expression requires operands | [outside_sql] |
+| `BooleanOperator` | `outside_sql` | This boolean operator is not supported | [outside_sql] |
+| `CTESearchCycle` | `outside_sql` | CTE SEARCH and CYCLE are not supported | [outside_sql] |
+| `CaseBranch` | `outside_sql` | A CASE WHEN branch is invalid | [outside_sql] |
+| `CastModifier` | `outside_sql` | Cast targets with modifiers or explicit array bounds are not supported | [outside_sql] |
+| `CastTargetMissing` | `outside_sql` | CAST requires a target type | [outside_sql] |
+| `CastValueMissing` | `outside_sql` | CAST requires a value | [outside_sql] |
+| `ColumnAlias` | `outside_sql` | Column aliases must be non-empty identifiers | [outside_sql] |
+| `ColumnQualification` | `outside_sql` | A column reference may have at most a table alias and a column name; use (column).field for object members | [outside_sql] |
+| `ColumnReference` | `outside_sql` | This column reference form is not supported | [outside_sql] |
+| `ConstantMembership` | `outside_sql` | Constant membership requires literal SELECT or UNION leaves and literal boolean filters, without ordering or pagination | [outside_sql] |
+| `ConstantMembershipKey` | `outside_sql` | This constant membership key has no supported equivalent rewrite | [outside_sql] |
+| `CorrelatedMembership` | `outside_sql` | Correlated membership requires equality column predicates between one inner source and current outer sources | [outside_sql] |
+| `CorrelatedScalar` | `conditional_pattern` | Correlated scalar subqueries are not supported; aggregate the inner source and JOIN the grouped result | For an equality comparison to a grouped MAX, aggregate by the correlation key in a subquery and JOIN that result. Preserve NULL and empty-group behavior. Other correlated forms have no verified SQL rewrite. |
+| `CurrentDate` | `outside_sql` | CURRENT_DATE is not supported; use a TIMESTAMP value or CURRENT_TIMESTAMP when equivalent | [outside_sql] |
+| `DistinctGrouping` | `outside_sql` | GROUP BY DISTINCT grouping sets require one source, unambiguous field keys, and an aggregate for the empty grouping set | [outside_sql] |
+| `DistinctOnNullOrdering` | `outside_sql` | DISTINCT ON with explicit NULLS ordering is not supported | [outside_sql] |
+| `DistinctOnPrefix` | `outside_sql` | DISTINCT ON expressions must match the leftmost ORDER BY expressions | [outside_sql] |
+| `DistinctWithGroupingSets` | `outside_sql` | SELECT DISTINCT with GROUPING SETS is not supported | [outside_sql] |
+| `EmptyProjection` | `outside_sql` | SELECT must produce at least one column | [outside_sql] |
+| `EqualityAny` | `outside_sql` | Array ANY supports equality comparisons only | [outside_sql] |
+| `ExpressionForm` | `outside_sql` | This expression form is not supported | [outside_sql] |
+| `ExpressionList` | `outside_sql` | An expression list cannot be empty | [outside_sql] |
+| `ExpressionOperator` | `outside_sql` | This expression operator is not supported | [outside_sql] |
+| `ExtractForm` | `outside_sql` | Use EXTRACT(field FROM expression) | [outside_sql] |
+| `ExtremaOperator` | `outside_sql` | This LEAST or GREATEST operation is not supported | [outside_sql] |
+| `FromFunction` | `outside_sql` | FROM table functions require exactly one UNNEST call | [outside_sql] |
+| `FromItem` | `outside_sql` | This FROM item is not supported | [outside_sql] |
+| `FullJoinUsing` | `outside_sql` | FULL JOIN USING is not supported; use FULL JOIN ON and project COALESCE(left_key, right_key) | [outside_sql] |
+| `FullPartitionFrame` | `outside_sql` | LAST_VALUE requires an explicit full-partition frame | [outside_sql] |
+| `FunctionQualification` | `outside_sql` | Schema-qualified function names are not supported | [outside_sql] |
+| `GroupingField` | `outside_sql` | Grouping-set keys must be direct field references | [outside_sql] |
+| `GroupingKeyType` | `outside_sql` | DISTINCT grouping-set keys must be TEXT or DOUBLE fields | [outside_sql] |
+| `HavingAggregateMath` | `outside_sql` | Math over aggregates in HAVING requires a grouped subquery; compute the aggregate then filter its output with WHERE | [outside_sql] |
+| `HavingRewrite` | `outside_sql` | This HAVING expression has no supported equivalent subquery rewrite | [outside_sql] |
+| `HavingSubquery` | `outside_sql` | HAVING subqueries require ordinary GROUP BY, no CTE or window, and output-name or ordinal ordering | [outside_sql] |
+| `JoinAliases` | `outside_sql` | JOIN aliases, NATURAL JOIN, and JOIN USING aliases are not supported | [outside_sql] |
+| `JoinKind` | `outside_sql` | Only INNER, LEFT, RIGHT, FULL, and CROSS JOIN are supported | [outside_sql] |
+| `JoinMembership` | `outside_sql` | JOIN membership requires inner-only joins or a two-source LEFT JOIN with qualified side-local predicates | [outside_sql] |
+| `JoinNesting` | `outside_sql` | Right-nested or aliased JOIN groups are not supported | [outside_sql] |
+| `JoinUsingName` | `outside_sql` | JOIN USING requires valid column names | [outside_sql] |
+| `LiteralKind` | `outside_sql` | This literal form is not supported | [outside_sql] |
+| `MembershipArity` | `outside_sql` | A scalar membership expression requires one operand | [outside_sql] |
+| `MembershipCTE` | `outside_sql` | Membership CTEs must be nonrecursive and have no column alias list or nested expression subquery | [outside_sql] |
+| `MembershipComparison` | `outside_sql` | Subquery membership supports IN and equality ANY only | [outside_sql] |
+| `MembershipKeyType` | `outside_sql` | Membership keys must be numeric or TEXT | [outside_sql] |
+| `MembershipOperand` | `outside_sql` | A membership operand must be a column, literal, or parameter | [outside_sql] |
+| `MembershipSource` | `outside_sql` | This membership source requires a FROM relation | [outside_sql] |
+| `MixedOuterJoin` | `outside_sql` | RIGHT or FULL JOIN cannot be mixed with comma-separated FROM groups; use one explicit JOIN chain | [outside_sql] |
+| `NestedMembership` | `outside_sql` | A membership operand cannot contain nested subqueries | [outside_sql] |
+| `NestedScalar` | `outside_sql` | Nested scalar subquery operands are not supported | [outside_sql] |
+| `NotArity` | `outside_sql` | NOT requires one operand | [outside_sql] |
+| `NthValueArity` | `outside_sql` | NTH_VALUE requires two arguments | [outside_sql] |
+| `NthValueShape` | `outside_sql` | NTH_VALUE requires a direct projection over one table, a positive literal index, numeric or TEXT values, and stable ordering including rec_id | [outside_sql] |
+| `ObjectMember` | `outside_sql` | Object member access requires exactly one field in the form (expression).field | [outside_sql] |
+| `ObjectSubscript` | `outside_sql` | Array subscripts and empty object member names are not supported | [outside_sql] |
+| `OperatorMissing` | `outside_sql` | An operator name is required | [outside_sql] |
+| `OrderItem` | `outside_sql` | This ORDER BY item is not supported | [outside_sql] |
+| `OrderUsing` | `outside_sql` | ORDER BY USING is not supported | [outside_sql] |
+| `RecursiveShape` | `outside_sql` | A recursive CTE requires UNION or UNION ALL between its anchor and recursive term | [outside_sql] |
+| `RowKeyType` | `outside_sql` | Row IN requires TEXT or DOUBLE keys; NOT IN also requires non-null keys on both sides | [outside_sql] |
+| `RowLock` | `outside_sql` | SELECT row locking is not supported | [outside_sql] |
+| `RowMembership` | `outside_sql` | Row membership requires an uncorrelated simple source and a top-level WHERE conjunct; nullable row NOT IN is not supported | [outside_sql] |
+| `ScalarAggregateOperand` | `outside_sql` | Scalar subquery operands require a single uncorrelated COUNT, SUM, AVG, MIN, or MAX in a non-grouped context | [outside_sql] |
+| `SelectClause` | `outside_sql` | This SELECT clause is not supported | [outside_sql] |
+| `SelectOnly` | `outside_sql` | Only SELECT statements are supported | [outside_sql] |
+| `SelectRelation` | `outside_sql` | A CTE or derived relation must contain SELECT | [outside_sql] |
+| `SelectTarget` | `outside_sql` | This SELECT target is not supported | [outside_sql] |
+| `SetBranches` | `outside_sql` | A set operation requires two SELECT branches | [outside_sql] |
+| `SetOperation` | `outside_sql` | This set operation is not supported | [outside_sql] |
+| `StarAlias` | `outside_sql` | A star projection cannot have an alias | [outside_sql] |
+| `StarContext` | `outside_sql` | A star is only valid in SELECT projection | [outside_sql] |
+| `StarJoinUsing` | `outside_sql` | SELECT * with JOIN USING requires explicit columns or a qualified alias.* | [outside_sql] |
+| `StarQualification` | `outside_sql` | Use * or table_alias.* for a star projection | [outside_sql] |
+| `StarUnnest` | `outside_sql` | Select the UNNEST alias explicitly instead of a star projection | [outside_sql] |
+| `StringAggregationForm` | `outside_sql` | STRING_AGG requires a literal separator without DISTINCT, FILTER, or OVER | An equivalent SQL form preserving ordering, filtering, and duplicate behavior has not been verified. [outside_sql] |
+| `StringAggregationSeparator` | `outside_sql` | STRING_AGG requires an ASCII separator without a zero byte | Replacing the requested separator would change the result. [outside_sql] |
+| `SubqueryForm` | `outside_sql` | This subquery form is not supported | [outside_sql] |
+| `SymmetricSubquery` | `outside_sql` | BETWEEN SYMMETRIC does not support subquery operands | [outside_sql] |
+| `TableColumnAliases` | `outside_sql` | Table column alias lists are not supported | [outside_sql] |
+| `TableQualification` | `outside_sql` | Schema-qualified table names are not supported | [outside_sql] |
+| `TemporalLiteral` | `outside_sql` | Only TIMESTAMP and INTERVAL typed literals are supported | [outside_sql] |
+| `TextPosition` | `outside_sql` | Character-based text position functions are not supported | [outside_sql] |
+| `TrimCharacters` | `outside_sql` | TRIM with PostgreSQL character semantics is not supported | Changing the trim spelling does not enable this operation. [outside_sql] |
+| `TypeName` | `outside_sql` | This type name is not supported | [outside_sql] |
+| `UnnestArity` | `outside_sql` | UNNEST requires exactly one argument | [outside_sql] |
+| `UnnestForm` | `outside_sql` | UNNEST WITH ORDINALITY, ROWS FROM, and column definitions are not supported | [outside_sql] |
+| `ValueFunction` | `outside_sql` | This SQL value function is not supported | [outside_sql] |
+| `ValueMemberKey` | `outside_sql` | Value membership requires TEXT or DOUBLE keys; computed INT keys are not supported | [outside_sql] |
+| `ValueSubqueryType` | `outside_sql` | Value subqueries require scalar numeric or TEXT operands without outer aggregates or windows | [outside_sql] |
+| `WindowInheritance` | `outside_sql` | A window cannot copy a frame or override inherited PARTITION BY or ORDER BY | [outside_sql] |
+| `WindowName` | `outside_sql` | A WINDOW definition must have a name | [outside_sql] |
+| `WithTies` | `outside_sql` | FETCH FIRST WITH TIES is not supported | [outside_sql] |
+
+## Rewrites that must not be substituted
+
+- `SQL_UNSUPPORTED_SYNTAX`: A SELECT subquery does not make the rejected comparison executable.
+- `SQL_UNSUPPORTED_SYNTAX`: Changing dimension 2 to dimension 1 changes NULL into an array length. Changing the dimension can change the result.
+- `SQL_UNSUPPORTED_SYNTAX`: Returning an object or address does not preserve a numeric coordinate. An address or complete object is not an equivalent result.
+- `SQL_UNSUPPORTED_SYNTAX`: An unqualified UNNEST recommendation can change row multiplicity; no general equivalent is proved. An equivalent SQL rewrite preserving row multiplicity has not been verified.
+- `SQL_UNSUPPORTED_SYNTAX`: Adding an arbitrary FROM relation changes row count, including on empty input. Adding an arbitrary table can change row count.
+- `SQL_INVALID_CAST`: The formatted timestamp differs by eight hours between Base SQL execution and the PostgreSQL query; do not recommend this SQL as equivalent. Calendar fields and the intended timezone must be validated before conversion; no equivalent SQL format has been verified.
+- `SQL_FUNCTION_NOT_FOUND`: Base SQL does not accept IS NOT DISTINCT FROM, which this rewrite needs to match NULL partition keys; no equivalent SQL rewrite has been verified. Preserve the first value under the intended ordering and NULL semantics.
+- `SQL_FUNCTION_NOT_FOUND`: Base SQL does not accept IS NOT DISTINCT FROM, which this rewrite needs to match NULL partition keys; no equivalent SQL rewrite has been verified. Preserve the last value under the intended ordering and NULL semantics.
+- `SQL_FUNCTION_NOT_FOUND`: Base SQL does not accept IS NOT DISTINCT FROM, which this rewrite needs to match NULL partition keys; no equivalent SQL rewrite has been verified. Preserve the requested position and return NULL for short partitions.

package/skills/lark-base-database/references/database-function-limitations.md

@@ -0,0 +1,29 @@
+# Database Function 能力边界
+
+在判断查询能力或处理编译与运行期错误时，以服务端诊断及[目录生成的错误与替代写法](base-sql-errors.generated.md)为事实源。这里保留参数协议和生成原则，不维护第二份函数或语法支持清单。
+
+## 判断与默认路径
+
+原则：先确认业务要保留的结果语义，再选择查询形式。判定时按诊断的位置、语义码和 Catalog 类型定位问题；默认采用生成参考中与当前条件匹配、已有验证的形式，并逐项核对其前提。
+
+例外：目录没有等价 SQL、前提不成立或改写会改变空值、行数及排序时，转到[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择消费结果的实现位置。单个组合失败不代表组成它的所有能力都不可用；版本或运行环境不一致时，保留诊断和 LogID，先核对事实源。
+
+## Stored Query 与分页
+
+- 参数 kind 不使用 `OPTION`；SingleSelect 选项名使用 `TEXT` 参数，并在 Page/FaaS 按 Catalog 选项白名单约束输入后显式比较 `(option_field).name`。
+- 不把 `OPTION`、`USER`、`CHAT`、`FILE`、`LOCATION`、`URL` 等对象类型声明为业务参数；参数只使用六种基础类型及其一维数组，允许的 null 位置以生成的 Schema 为准。
+- 不通过移除服务端筛选、读取固定前 N 条后在 Page 分页来声称完整分页或全量导出。
+
+## 查询生成边界
+
+默认逐列投影，保持输出 Schema 稳定；连接的每一侧使用明确的表或带别名的派生表，分阶段表达复杂查询。常规生成优先简单连接、顶层查询与带别名的派生表，而不是依靠深层组合表达全部业务逻辑。确需复杂组合时，依据生成参考和目标环境验证决定，而不将生成偏好当作平台能力结论。
+
+Database Function 需要 Catalog 中真实表依赖，以确定数据上下文；与 Base 数据无关的计算按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)处理。动态返回规模由调用方校验为非负整数并限制最大值；服务端资源预算以诊断中的实际限制为准。
+
+## 按位置取值
+
+先明确分区、排序、并列值与空分区的业务含义，再查[生成参考中的修复策略](base-sql-errors.generated.md)。默认只采用满足前提的已验证形式；没有等价形式时沿用[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)。
+
+## NULL 与数值边界
+
+改写前明确空值、空集合、数值精度和错误行为是否属于结果契约。默认保留业务所需语义，并按[生成参考的前提与验证说明](base-sql-errors.generated.md)选择修法；防护写法会改变错误行为时，先确认业务接受该变化。需要 SQL 外处理的部分统一按[实现位置原则](../SKILL.md#sql-外实现放在哪)决定，不把截断结果或丢失空值的结果当作等价替代。