Add support for null literals in query parameters

[ragnorc]

Summary

This PR adds comprehensive support for null literals in query parameters throughout the omnigraph compiler and executor. Previously, null values were rejected or unsupported. Now they are properly handled for nullable parameters while maintaining type safety for non-nullable parameters.

Key Changes

• Parameter Handling (query_input.rs)

  • Added explicit null checking in json_params_to_param_map() to validate null values against parameter nullability
  • Null values are now rejected for non-nullable parameters with a clear error message
  • Omitted nullable parameters are automatically filled with Literal::Null
  • Inferred parameters can now accept null values (previously rejected)

• Type System (query/typecheck.rs)

  • Added Literal::Null variant to the Literal enum
  • Updated literal_type() to infer null as a nullable String type (type-agnostic default)
  • Enhanced check_literal_type() to validate null compatibility with expected property types
  • Null is now accepted for any nullable property type

• SQL Execution (exec/mod.rs)

  • Added SQL NULL conversion in literal_to_sql()
  • Added null array creation in literal_to_array() for constant arrays
  • Updated literal_scalar_type() to handle null literals with String as default type

• Test Coverage

  • Added 5 comprehensive tests covering:
    • Omitted nullable parameters becoming null
    • Explicit null values for nullable parameters
    • Non-nullable parameters rejecting null with proper error
    • Nullable parameters with actual values working normally
    • Inferred null parameters becoming Literal::Null

Implementation Details

The changes maintain backward compatibility while adding null support. Null handling is consistent across parameter declaration (typed), inference (untyped), and execution layers. The type system defaults null to String when type inference is needed, allowing null to be compatible with any nullable type during type checking.

https://claude.ai/code/session_014oGFKL7EVg1b2cyPgt9Gne

---

Note

Medium Risk
Changes how query parameters are parsed, typechecked, and executed by introducing null as a first-class literal; mistakes could alter runtime filtering/mutation behavior or surface new edge cases around nullability and SQL/Arrow typing.

Overview
Adds a Literal::Null variant and wires it through the compiler and runtime so null can be provided (or omitted) for nullable query parameters.

json_params_to_param_map now accepts JSON null, rejects it for non-nullable declared params, and auto-fills omitted/absent nullable params with Literal::Null (including when params is null/missing), with new unit tests covering these cases.

Typechecking and execution are updated to treat null as compatible with any nullable property type, emit SQL NULL in pushdown, and build Arrow null arrays when projecting constants or writing mutation values.

^{Reviewed by Cursor Bugbot for commit c943d97. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98482881b6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Default nullable params even when params object is absent

The new nullable-defaulting logic only runs after parsing a JSON object, so requests that pass params = None or params = null still return early with an empty map and never insert Literal::Null for declared nullable parameters. In the CLI/server call paths that omit the params payload entirely, queries with nullable params can still fail later with parameter '<name>' not provided, which contradicts the new omitted-null behavior. Apply the same defaulting in the early-return path as well.

Useful? React with 👍 / 👎.

[cursor]

Null literal creates wrong array type in projections

Medium Severity

literal_to_array hardcodes DataType::Utf8 for Literal::Null, but the parameter's declared type could be anything (e.g., I64?, Bool?, Date?). While the filter path has a cast step that compensates, the projection path in evaluate_projection uses literal_to_array directly to build result columns. This means a null value for, say, an I64? parameter produces a Utf8 column in the result schema, whereas a non-null value produces an Int64 column — an inconsistency that can break clients depending on stable schemas. The sibling function literal_to_typed_array correctly uses the target data_type, but literal_to_array has no type context to do the same.

 

^{Reviewed by Cursor Bugbot for commit 9848288. Configure here.}

[cursor]

SQL pushdown generates = NULL instead of IS NULL

Medium Severity

literal_to_sql converts Literal::Null to the string "NULL", which ir_filter_to_sql then uses in comparisons like column = NULL. In SQL, column = NULL always evaluates to NULL (falsy), never matching any rows — the correct form is column IS NULL. Filters using null parameters silently return empty results instead of matching null column values.

Additional Locations (1)

• crates/omnigraph/src/exec/query.rs#L1123-L1142

 

^{Reviewed by Cursor Bugbot for commit 37b7a94. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 4 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c943d97. Configure here.}

[cursor]

Null in literal arrays breaks non-String type lists

Medium Severity

literal_scalar_type and literal_type both default Literal::Null to ScalarType::String. When a null appears inside a list alongside non-String elements (e.g., [null, 42]), list_scalar_type and the typecheck list validation see mismatched types (String vs I64) and reject the list with a confusing "elements must share a compatible scalar type" error. Null in a list is type-agnostic and needs to be treated as compatible with the surrounding element types rather than hardcoded to String.

Additional Locations (1)

• crates/omnigraph-compiler/src/query/typecheck.rs#L1439-L1440

 

^{Reviewed by Cursor Bugbot for commit c943d97. Configure here.}

[cursor]

Null literal array hardcodes Utf8 ignoring actual type

Medium Severity

literal_to_array creates a DataType::Utf8 null array for Literal::Null regardless of context. In contrast, literal_to_typed_array in mutation.rs correctly uses the target data_type. When a null parameter is projected in a result set, the column will have type Utf8 instead of the expected schema type, potentially causing type mismatches or incorrect schema inference in downstream consumers.

 

^{Reviewed by Cursor Bugbot for commit c943d97. Configure here.}