feat(postgrest): add an isUnknown filter method

[spydon]

What

PostgrestFilterBuilder.isFilter takes a bool?, so it covers is.null, is.true and is.false, but not PostgREST's fourth is value, unknown.

Rather than replacing the bool? with an enum (a breaking change), this adds a dedicated method for the rarely used state, as suggested in #1609 (comment):

await supabase.from('users').select().isUnknown('confirmed');

Changes

• PostgrestFilterBuilder.isUnknown(String column) appends is.unknown, with a cross-reference from the isFilter docs.
• Test asserting the generated query parameter is is.unknown and that PostgREST accepts the filter.
• Registered the new symbol under database.using_filters.is in sdk-compliance.yaml.

Notes

isUnknown was deliberately not added to SupabaseStreamFilterBuilder. Realtime validates filter values by casting them to the column type server-side, and unknown is not castable to boolean, so exposing it there could not be verified to work. On a boolean column is unknown is also equivalent to is null, which streams already support.

Closes #1609

Summary by CodeRabbit

• New Features

  • Added an isUnknown filter for querying rows where a SQL boolean value is UNKNOWN.
  • Updated filter guidance to clarify when to use this option.

• Documentation

  • Updated compliance documentation to include the new filter capability.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d292ad3e-6f53-4a89-8dd2-1c12a96bbd9b

📥 Commits

Reviewing files that changed from the base of the PR and between fa7533c and e674df4.

📒 Files selected for processing (3)

• packages/postgrest/lib/src/postgrest_filter_builder.dart
• packages/postgrest/test/filter_test.dart
• sdk-compliance.yaml

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The PostgREST client now supports filtering for SQL UNKNOWN values through PostgrestFilterBuilder.isUnknown. Tests verify query generation and results. The SDK compliance matrix lists the new method.

Changes

Unknown filter support

Layer / File(s)	Summary
Unknown filter API packages/postgrest/lib/src/postgrest_filter_builder.dart	Adds isUnknown(String column) with the is.unknown search parameter and updates the isFilter documentation.
Unknown filter validation packages/postgrest/test/filter_test.dart, sdk-compliance.yaml	Tests query generation and empty results for a non-null column. The compliance matrix lists PostgrestFilterBuilder.isUnknown.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to e674d

This adds an optional PostgREST filter for the UNKNOWN state without changing existing behavior or authorization paths; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: vinzent03, dshukertjr

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding the PostgREST isUnknown filter method.
Linked Issues check	✅ Passed	The PR satisfies issue #1609 by supporting the PostgREST unknown value through PostgrestFilterBuilder.isUnknown, while preserving the existing isFilter API. It includes documentation, tests, and…
Out of Scope Changes check	✅ Passed	All changes support issue #1609 and the stated objectives. No unrelated code or configuration changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Linked Issues check

Explanation

The PR satisfies issue #1609 by supporting the PostgREST unknown value through PostgrestFilterBuilder.isUnknown, while preserving the existing isFilter API. It includes documentation, tests, and compliance registration.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lukasklingsbo/sdk-1656-featpostgrest-add-an-isunknown-filter-method

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}