@lark-base-open/base-database-cli 1.3.7 → 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

@@ -1,6 +1,12 @@
 # Database Function 能力边界
 
-仅在判断支持集之外的查询语法、评审或排查查询语句，或者处理查询编译与运行兼容失败时读取。本文件是当前生成与兼容策略：明确不支持的协议不使用；“默认不生成”“支持不统一”属于保守生成边界，不据此声称平台整体不支持。已知限制正常开发直接遵守，只有版本或验证证据变化时复核。以下形态不写入常规 `main.sql`：
+在判断查询能力或处理编译与运行期错误时，以服务端诊断及[目录生成的错误与替代写法](base-sql-errors.generated.md)为事实源。这里保留参数协议和生成原则，不维护第二份函数或语法支持清单。
+
+## 判断与默认路径
+
+原则：先确认业务要保留的结果语义，再选择查询形式。判定时按诊断的位置、语义码和 Catalog 类型定位问题；默认采用生成参考中与当前条件匹配、已有验证的形式，并逐项核对其前提。
+
+例外：目录没有等价 SQL、前提不成立或改写会改变空值、行数及排序时，转到[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择消费结果的实现位置。单个组合失败不代表组成它的所有能力都不可用；版本或运行环境不一致时，保留诊断和 LogID，先核对事实源。
 
 ## Stored Query 与分页
 
@@ -8,39 +14,16 @@
 - 不把 `OPTION`、`USER`、`CHAT`、`FILE`、`LOCATION`、`URL` 等对象类型声明为业务参数；参数只使用六种基础类型及其一维数组，允许的 null 位置以生成的 Schema 为准。
 - 不通过移除服务端筛选、读取固定前 N 条后在 Page 分页来声称完整分页或全量导出。
 
-## 查询结构与引用
-
-- 查询结构：`INSERT`、`UPDATE`、`DELETE`、`MERGE`、递归 CTE、嵌套 CTE、`LATERAL`，以及右侧会展开为多个 FROM item 的右深嵌套 JOIN。`SELECT *`、`table.*` 默认不生成，保持输出列稳定。`UNION`、`INTERSECT`、`EXCEPT`（可带 `ALL`）可用，但各分支对应列的类型必须完全相同。
-- 无真实表依赖查询：`SELECT 1`、`SELECT $1`、仅 `FROM (SELECT 1) AS x`、仅常量 CTE 或仅 `UNNEST(...)` 的查询。绑定 Base 的 Database Function 必须直接或经由派生表/CTE 引用至少一个 Catalog 真实表，否则运行时可能因查询未引用可路由表而无法确定数据上下文。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
-- 分组：`GROUP BY` 超过 5 项；需要更多展示列时拆成聚合查询与明细查询后在 Page/FaaS 合并。
-- JOIN：`NATURAL JOIN`、`FULL JOIN ... USING`、JOIN group alias、`LEFT JOIN UNNEST(...)`、`INNER JOIN UNNEST(...)`、含 `GROUP BY` 或聚合函数的派生表 JOIN，以及单条查询超过 10 个 JOIN。`RIGHT JOIN`、`FULL JOIN`、`JOIN ... USING` 可用，常规生成仍优先 `INNER` / `LEFT JOIN`。
-- 列成员：禁止 `table_alias.user_field.id` 和 `"人员字段".id`；UDT 列只使用 PostgreSQL 括号语法 `(table_alias.user_field).id` 或 `("人员字段").id`，`UNNEST` 后的 range alias 成员仍写 `u.id`。
-- 派生对象：把 `USER`、`CHAT`、`FILE`、`URL` 完整对象投影到派生表后再 JOIN。静态校验可能接受该形态，实际执行仍可能返回查询不受支持的错误。
-
-## 类型、表达式与字段操作
-
-- 类型与表达式：`CURRENT_DATE`、`DATE` 类型、`NOW()`，数字转 `TEXT`（`x::text`）、列值转 `TIMESTAMP` / `INTERVAL`（这两种转换只接受字符串字面量），以及固定支持集之外的函数调用。可用的显式转换是 `::int`、`::bigint`、`::float8`、`::numeric`、`::bool`。
-- 非 PostgreSQL 写法不支持：`DATE_FORMAT` 改用 `TO_CHAR(ts, 'YYYY-MM')`，`ENDS_WITH` 改用 `LIKE '%x'`，单参数 `ARRAY_LENGTH(arr)` 改用 `ARRAY_LENGTH(arr, 1)` 或 `CARDINALITY(arr)`，`ROUND(x, n)` 改用 `ROUND(x::numeric, n)`，对小数取模 `x % n` 不支持。
-- `||`、`CONCAT` 两侧都必须是 `TEXT`，不会把数字隐式转为文本；`COALESCE`、`NULLIF`、集合运算只在 `INT` 与 `DOUBLE` 之间统一为 `DOUBLE`，其他类型要先写成同类型。
-- 条件聚合：不要写 `SUM/AVG(CASE WHEN ... THEN 1 ELSE 0 END)`；改用 `SUM(CASE WHEN ... THEN 1.0 ELSE 0.0 END)`。
-- `ILIKE`、`NOT ILIKE`：字段支持不统一，正常查询使用 `LIKE`、`NOT LIKE`。
-- 相关标量子查询在 WHERE、投影、HAVING、ORDER BY 中均不支持；先在派生表按关联键 GROUP BY，再 JOIN 回外层（复杂组合应拆成两个 Database Function）。非相关子查询只使用已校验的形态，不将这一限制泛化为所有子查询都不可用。
-- 子查询表达式：`EXISTS` 在投影、`ORDER BY`、`OR` / `CASE` 下的形态默认不生成；相关子查询的非等值关联（例如 `inner.t < outer.t`）。改用派生表 JOIN，或用单独 Database Function 查询后在 Page/FaaS 合并。`WHERE` 中的 `IN` / `NOT IN` / `EXISTS` 子查询和等值相关子查询可用。
-- 聚合与窗口函数：`PERCENTILE_CONT` / `PERCENTILE_DISC`、`MEDIAN`、`WITHIN GROUP`、聚合内 `ORDER BY`；带 `ORDER BY` 的聚合窗口（逐行累计）、`CURRENT ROW` 或有界的窗口范围、未写整分区范围的 `LAST_VALUE`；`STDDEV` / `VARIANCE` 作为窗口函数。`STDDEV`、`VARIANCE` 作为普通聚合可用，`ROW_NUMBER`、`RANK` 等排名窗口可用。
-- 字符串函数：`LENGTH`、`CHAR_LENGTH`、`LEFT`、`RIGHT`、`SUBSTRING`、`LPAD`、`RPAD`、`TRIM` / `LTRIM` / `RTRIM`、`SPLIT` / `SPLIT_PART`、`REGEXP` / `RLIKE` / `REGEXP_REPLACE`；`STRPOS` / `POSITION` 取具体位置（只能与 0 或 1 比较，用于判断是否包含）。`REPLACE` 可用。
-- 数字函数：`POWER`、`SQRT`、`LOG`、`EXP`、`TRUNC`；`MOD` 的参数不是整数。
-- 日期函数：`DATEDIFF`、`AGE`，以及其他未列入支持集的时间间隔函数；月、季、年单位的 `INTERVAL`；`EXTRACT` / `DATE_PART` 的 `dow`、`doy`、`week`、`quarter`；`DATE_PART('epoch', ts)`（改写为 `EXTRACT(EPOCH FROM ts)`）；`DATE_TRUNC` 截到时、分、秒，以及 `DATE_TRUNC` 结果再参与比较、相减或 `EXTRACT`。
-- `rec_id`、`TEXT`、Phone：顺序比较、`BETWEEN`、`NOT BETWEEN`。文本日期字符串不能用 `<`、`<=`、`>`、`>=` 做范围筛选；需要日期范围时把字段建成 DateTime/TIMESTAMP，或改用 Text 支持的 `=`、`IN`、`LIKE` 后在 Page/FaaS 中判断范围。
-- Checkbox：`IN`、顺序比较、`BETWEEN`、`NOT BETWEEN`。
-- DateTime：`IN`、`NOT IN`、`LIKE`、`ILIKE`。
-- SingleSelect：与 TEXT、`.name` 或 `.id` 等成员标量之间的隐式比较，顺序比较、`BETWEEN`、`LIKE`、`ILIKE`，以及与 `''` 空字符串比较；动态选项名筛选显式使用 `.name` 和 `TEXT` 参数。
-- MultiSelect：`LIKE`。
-
-- 参数化数组成员判断仅支持 `TEXT表达式 = ANY($n)`，且 `$n` 声明为 `TEXT[]`。其他类型先用同类型标量参数展开为等值条件；不要用 `IN ($n)` 展开数组参数。
-
-## 不要误判为整体不支持
-
-- `LIKE $1` 本身可用，参数携带 `%`；复合查询失败时分别检查参数 kind 与错误节点，不因单条失败就判定参数化 `LIMIT/OFFSET` 不支持。
-- OPTION 与同类型 OPTION 可以直接比较；与固定选项名或 `TEXT` 参数比较时必须显式访问 `.name` 或 `.id`。其他 UDT 同样不能和其成员标量隐式比较。
-- 参数化 `LIMIT $n` / `OFFSET $n` 可用；页面输入不能直接决定返回规模，确需动态条数时由 Page/FaaS 先校验为非负整数并限制最大值。
-- 支持集内的 `CASE`、`COALESCE`、`INNER JOIN`、`LEFT JOIN`、`CROSS JOIN`、非递归顶层 CTE、派生标量列、`FROM` 子查询、`WHERE` 中的 `IN` / `EXISTS` 子查询、逗号连接或 `CROSS JOIN` 形态的 `UNNEST`、`TIMESTAMP` 字面量、固定时长的 `INTERVAL`、`EXTRACT`、`TO_CHAR`、时间间隔运算、`ARRAY_AGG`、`STRING_AGG`、排名窗口、`CEIL` 和 `FLOOR` 可以使用；某个复合查询失败时先按错误节点缩小，不把这些能力整体降级。
+## 查询生成边界
+
+默认逐列投影，保持输出 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-外实现放在哪)决定，不把截断结果或丢失空值的结果当作等价替代。

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

@@ -151,7 +151,7 @@ WHERE f."分组" = ANY($1)
 LIMIT 30
 ```
 
-对应参数声明为 `{"kind":"TEXT[]"}`，例如调用 `params: [["重点", "普通"]]`。左侧必须是 `TEXT`，右侧必须是一维 `TEXT[]` 位置参数；其他元素类型的参数化 `ANY` 尚不支持。空数组不会选中记录；整个数组为 `null`，或没有匹配且数组含 `null` 时，表达式为 `null`，`WHERE` 不选中该行。不要把 `IN ($1)` 当作数组展开，也不要对标量字段直接使用 `<@`。显式 `ARRAY[字段] <@ $1` 是数组包含判断，与 `ANY` 在含 `null` 时的布尔结果不同。
+对应参数声明为 `{"kind":"TEXT[]"}`，例如调用 `params: [["重点", "普通"]]`。本例左侧为 `TEXT`，右侧为一维 `TEXT[]` 位置参数；其他形态按[生成参考](base-sql-errors.generated.md)判定。空数组不会选中记录。数组含 `null` 时不保证 PostgreSQL 三值语义，具体结果与预处理规则见[NULL 与数值边界](database-function-limitations.md#null-与数值边界)。成员判断与数组展开的区别及修法以[生成参考](base-sql-errors.generated.md)为准。
 
 无参数 Function 可以省略 `meta` 或 `meta.params`；归档统一补成 `{"params":[]}`。
 
@@ -159,45 +159,20 @@ Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固
 
 ## 查询约束
 
-只编写只读 `SELECT`，页面输入只能进入位置参数。查询使用以下支持集：
+只编写只读 `SELECT`，页面输入只能进入位置参数。具体能力、拒绝条件与修法以[目录生成的错误与替代写法](base-sql-errors.generated.md)为准；生成原则见[能力边界](database-function-limitations.md#查询生成边界)。
 
 - 每条查询的最终查询计划必须引用至少一个 Catalog 中的真实表，用于 Project 执行时选择可路由的表依赖。根 `FROM` 可以是带别名的 `FROM (SELECT ...) AS alias` 派生表，但该派生表或它依赖的 CTE 必须读取真实表。
-- 不要用 Database Function 实现纯常量、纯参数、仅 `FROM (SELECT ...)`、仅 CTE 常量或仅 `UNNEST(...)` 的查询；这些查询没有真实表依赖，会在绑定 Base 的 Validate 或 Execute 阶段失败。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
-- 查询结构使用显式投影、`WHERE`、`GROUP BY`、`HAVING`、`ORDER BY`；不使用 `SELECT *` 或 `table.*`。`GROUP BY` 最多 5 项。
-- 连接使用 `INNER JOIN`、`LEFT JOIN`、`CROSS JOIN` 或逗号连接。每个 JOIN 的右侧保持为一个表或一个带别名的派生表；`UNNEST` 只能写成逗号连接或 `CROSS JOIN UNNEST(...)`，禁止生成 `LEFT JOIN UNNEST` 或 `INNER JOIN UNNEST`。不要把含 `GROUP BY`、`COUNT`、`SUM`、`AVG`、`MIN` 或 `MAX` 的聚合派生表再 `JOIN` 回主表。单条查询的 JOIN 总数不超过 10。
-- 非递归顶层 CTE 可用；正常建站优先用带别名的 `FROM (SELECT ...) AS alias`，不要写递归 CTE 或嵌套 CTE。
-- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过派生表输出列名引用结果。成员判断可以直接写 `WHERE x IN (SELECT ...)`、`NOT IN`、`EXISTS`、`NOT EXISTS`；相关子查询只使用等值关联（`inner.k = outer.k`）。投影、`ORDER BY`、`OR` 或 `CASE` 之下的标量子查询和 `EXISTS` 默认不生成，需要时拆成派生表或单独查询。
+- 默认逐列投影并使用 `AS snake_case`，保持输出 Schema 稳定；连接的每一侧保持为一个表或带别名的派生表。常规生成优先简单连接、顶层查询和带别名的派生表，复杂组合依据生成参考及验证结果决定。
+- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过输出列名引用结果。需要其他形态时先核对业务语义与生成参考，不把默认生成偏好当作支持清单。
 - 列表使用有界 `LIMIT` 和稳定排序；排序值可能重复时最后按 `rec_id` 排序。不把截断结果的前端分页视为完整分页或全量导出。
-- 返回字段逐列列出并使用 `AS snake_case`。
 - 搜索写 `field LIKE $1`，由参数携带 `%`。
-- `IN (..., NULL)` / `NOT IN (..., NULL)` 保留三值逻辑：未命中但列表含 NULL 时结果为 NULL，WHERE 不选中该行。字符串 `a || b` 任一侧为 NULL 时结果为 NULL；`CONCAT(a,b)` 则跳过 NULL。
-- UDT 只与相同 UDT 类型直接比较；UDT 与成员标量之间没有隐式比较。OPTION 展示名筛选写 `(option_field).name = $n` / `IN (...)`，ID 筛选写 `(option_field).id = $n`；不要写 `option_field = $n`，也不要把 OPTION 或其成员与 `''` 比较。
-- 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。
-- UDT 列成员统一使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 可写 `("附件").token`、`.name`、`.mime_type`、`.size`；不再使用 `"字段".member` 或 `t."字段".member`。多值对象需要逐元素读取时写 `FROM 表 AS t, UNNEST(t."人员") AS u`，range alias 成员仍写 `u.id`。
-- 不把 `USER`、`CHAT`、`FILE`、`URL` 完整对象投影到派生表后再 JOIN；需要身份过滤时在对象字段所在的真实表查询中直接比较标量子字段。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
-- 集合字段只使用 PostgreSQL 数组运算符：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。不要生成 `ARRAY_CONTAINS` 或 `ARRAY_OVERLAP`。单值关联的 `sqlType` 是 `TEXT`，按文本标量使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE`，不要对它使用数组运算符。只有业务本来就是 INNER/逐元素明细语义时，才通过逗号连接或 `CROSS JOIN UNNEST(...)` 展开；展开会过滤空集合主表行，不能替代 `LEFT JOIN UNNEST`。
-- 条件分支：`CASE WHEN bool_expr THEN value ... ELSE value END` 与 `CASE expr WHEN value THEN ... END` 都可用，各分支结果类型一致（`INT` 与 `DOUBLE` 会统一为 `DOUBLE`）。空值兜底可用 `COALESCE(x, fallback)` / `NULLIF`，参数类型必须完全相同，`INT` 与 `DOUBLE` 混用时先写成同类型，例如 `COALESCE(x, 0.0)`。
-- 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。不要对 `TEXT` 日期字符串使用顺序比较；若业务必须做日期范围筛选，把 Base 字段建成 DateTime/TIMESTAMP。
-- 时间格式化与分桶：按月、按天展示写 `TO_CHAR(ts, 'YYYY-MM')`，格式只使用 `YYYY`、`MM`、`DD`、`HH24`、`MI`、`SS` 及分隔符；按天、周、月、季、年分组也可写 `DATE_TRUNC('month', ts)`，其结果只用于投影、`GROUP BY`、`ORDER BY`，不再参与比较或运算。时间偏移使用固定时长的 `INTERVAL`（毫秒到周），不使用月、年单位；需要按自然月计算的范围由 Page/FaaS 算好边界后作为 `TIMESTAMP` 参数传入。`EXTRACT` / `DATE_PART` 返回 `DOUBLE`。
-- 聚合函数使用 `COUNT(*)`、`COUNT(expr)`、`SUM(NUMBER)`、`AVG(NUMBER)`、`MIN(scalar)`、`MAX(scalar)`；`ARRAY_AGG(expr)` 可用但默认少生成。聚合结果需要回填到列表行时，拆成列表查询、聚合查询和必要的明细查询，在 Page/FaaS 按稳定业务键合并。
-- 条件计数、通过率等聚合写 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END)`；不要生成 `SUM/AVG(CASE WHEN cond THEN 1 ELSE 0 END)`。行数统计用 `COUNT(*)` / `COUNT(expr)`。
-- 窗口函数可用：`ROW_NUMBER`、`RANK`、`DENSE_RANK`、`PERCENT_RANK`、`CUME_DIST`、`NTILE(n)`、`LAG` / `LEAD`、`FIRST_VALUE`，以及 `COUNT` / `SUM` / `AVG` / `MIN` / `MAX` 作为整个分区的汇总。“每组最新一条”写派生表 `ROW_NUMBER() OVER (PARTITION BY k ORDER BY t DESC, rec_id DESC) AS rn`，外层 `WHERE rn = 1`。窗口只支持整个分区的计算范围：带 `ORDER BY` 的聚合窗口（逐行累计）、`ROWS/RANGE BETWEEN ... CURRENT ROW` 等范围不支持，累计值在 Page/FaaS 中计算；`LAST_VALUE` 只能配合 `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING`。
-- 字符串函数使用 `LOWER(TEXT)`、`UPPER(TEXT)`、`CONCAT(TEXT, ...)`、`CONCAT_WS(sep, TEXT, ...)`、`REPLACE`、`STARTS_WITH`，拼接也可写 `||`（两侧都是 `TEXT`）。包含判断写 `STRPOS(text, 'x') > 0`，结尾匹配写 `text LIKE '%x'`；`STRPOS` 只能与 0 或 1 比较，不能取具体位置。`LENGTH`、`LEFT`、`RIGHT`、`SUBSTRING`、`LPAD`、`RPAD`、`TRIM` / `LTRIM` / `RTRIM` 和正则函数不支持，长度、截取、去空白、拆分在 Page/FaaS 中处理。
-- 数字计算使用 `+`、`-`、`*`、`/`、`%` / `MOD`（仅整数）、`ABS`、`CEIL`、`FLOOR`、`ROUND(x)`；保留 n 位小数写 `ROUND(x::numeric, n)`，不写 `ROUND(x, n)`。两个整数相除按 PostgreSQL 做整数除法（`7 / 2 = 3`，`COUNT(a) / COUNT(*)` 也是整数除法），比例、通过率写 `COUNT(a)::float8 / COUNT(*)` 或 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END) / COUNT(*)`。
-
-字段筛选使用以下支持形态：
-
-| 字段类型 | 支持的筛选形态 |
-|---|---|
-| `rec_id`、`TEXT`、Phone | `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
-| `INT`、`DOUBLE` | `=`、`IN`、`NOT IN`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
-| `BOOL` | `= TRUE`、`= FALSE` |
-| `TIMESTAMP` | 与 `TIMESTAMP` 参数使用 `=`、`!=`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
-| `OPTION` | 显式比较 `.name` 或 `.id`；整个 OPTION 只与 OPTION 比较 |
-| `AUTONUMBER` | `.sequence` 做数值比较、排序和计算；`.number` 做文本展示或等值筛选 |
-| 单值关联（Catalog `sqlType.kind = TEXT`） | 按 `TEXT` 使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
-| 多选、多值关联等集合（Catalog `sqlType.kind = ARRAY`） | 只使用 `@>`、`<@`、`&&`；UDT 数组先显式访问 `.id` / `.name` 成员数组 |
-| `USER`、`CHAT`、`FILE`、`URL` | 使用括号语法比较已声明的标量子字段；FILE 为 `.token/.name/.mime_type/.size`，URL 为 `.text/.link`；多值对象只有逐元素明细语义才展开 |
+- 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
+- UDT 列成员使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 的成员为 `.token/.name/.mime_type/.size`；逐元素读取后的 range alias 成员写 `u.id`。
+- 集合字段的 PostgreSQL 数组运算符含义为：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。先用 Catalog 的 `sqlType` 区分标量与集合，再按生成参考判断操作是否适用；展开集合前确认业务是否允许改变主表行数。
+- 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。
+- 窗口、聚合、字符串、日期和数值计算先明确结果契约，再查[目录生成的修法与已验证 SQL](base-sql-errors.generated.md)。默认采用满足前提的形式；例外是没有等价 SQL 或改写改变所需语义，此时统一按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择实现位置。
+
+字段类型和成员来自 Catalog，输入按本节参数协议声明；适用的字段操作与修复路径查[生成参考](base-sql-errors.generated.md)，而不是从字段名称推断。示例演示参数和结果消费，不作为完整能力清单。
 
 条件聚合示例：
 
@@ -286,7 +261,7 @@ ORDER BY o."订单号" DESC, o.rec_id DESC
 LIMIT 20
 ```
 
-如果没有真实目标表可 JOIN，又必须保留空集合主表行，拆成主表查询与明细展开查询，并在 Page/FaaS 里按主表 `rec_id` 左合并。拆分后的输入若在开始时已经确定，应并发调用；不要用 `CROSS JOIN UNNEST` 冒充 LEFT 语义。
+如果没有真实目标表可 JOIN，又需要保留空集合主表行，先核对[生成参考中的语义前提](base-sql-errors.generated.md)；没有等价形式时按[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)处理。拆分后的输入若在开始时已经确定，应并发调用。
 
 搜索、筛选、关联和聚合尽量在查询中完成。没有关系、不同步消费或需要隔离失败语义的结果集可以拆分；拆分后的输入若在开始时已经确定，应并发调用。
 
@@ -303,7 +278,7 @@ await invokeDatabaseFunction<{ rows: unknown[] }>(
 )
 ```
 
-FaaS handler 内部使用 context，projectId 为当前 应用 的工程常量：
+FaaS handler 内部使用 context，projectId 为当前应用的工程常量：
 
 ```ts
 await context.invokeFunction({
@@ -329,12 +304,11 @@ await context.invokeFunction({
         "record_id": "recxxx",
         "title": "准备评审",
         "status": "待处理",
-        "due_at": 1784311200000
+        "due_at": "2026-07-18 10:00:00.000"
       }
     ],
     "columns": [],
     "row_count": 1,
-    "fxdb_version": "...",
     "log_id": "..."
   },
   "code": 0,

package/skills/lark-base-database/references/development.md

@@ -86,7 +86,7 @@ metadata 只声明输入，因此生成文件只约束调用参数。调用结
 
 ## Page 调用
 
-默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的 应用 名称，不留空。
+默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的应用名称，不留空。
 
 默认 Page 必须引用并渲染 `page/src/components/floating-button/index.tsx` 中的 `FloatingButton` 组件。该组件自行解析应用 token，不接受 `projectId`。悬浮控件仅在正式环境向服务端判定有管理权限的访问者提供「编辑应用」入口。
 
@@ -233,7 +233,7 @@ AI 与 Base 数据组合时保持既有边界：先用 Database Function 读取
 | Page `invokeDatabaseFunction` | 检查一次顶层 `code`，再校验 operation 的 `data`                                   |
 | Database Function             | `data` 为 ResultJSON，包含 rows 等查询信息                                        |
 | FaaS handler                  | 返回 `{data,code,msg}`，data 为业务结果，不再由 Page 二次解包                     |
-| FaaS 下游记录写入             | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录-写入协议) |
+| FaaS 下游记录写入             | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录写入协议) |
 
 不要把 SDK 的 `code===0` 套在 CLI 外层，也不要将 CLI 外层的 data 当作 handler 业务数据。raw API 的命令封装与业务响应按当前 lark-cli reference 分别解析。