feat: add where filters to osograph (#5662)

* feat: add `type-safe` query builder and where clause parser

* feat: add `where` parameter support to all list queries with `JSON` scalar

* feat: add where clause validation schemas with `createWhereSchema` factory

* refactor: add `FilterableConnectionArgs` type and update resolver helper utilities

* feat: implement filtering support across all `OsoGraph` resolvers

* chore: add `graphql-scalars` dependency for JSON scalar support

* refactor: use `graphql-scalars` for DateTime and JSON scalar resolvers

* docs: add filtering guide with where clause examples for `OsoGraph`

* chore: add `where` argument to `Viewer.runs`

* chore: run `codegen` scripts

* chore: use `query-builder` + `where` format

* feat: implement `queryWithPagination` helper

* chore: run `codegen` scripts

* feat: use static `basePredicate` option

* chore: update `osograph` docs

Author: Jabolol

apps/docs/docs/guides/ops/osograph.md

@@ -5,6 +5,7 @@ extend schema
   )
 
 scalar DateTime
+scalar JSON
 
 enum MemberRole {
   owner

apps/frontend/app/api/v1/osograph/schema/graphql/base.graphql

@@ -7,8 +7,8 @@ type DataModel {
   isEnabled: Boolean!
   createdAt: DateTime!
   updatedAt: DateTime!
-  revisions(first: Int = 50, after: String): DataModelRevisionConnection!
-  releases(first: Int = 50, after: String): DataModelReleaseConnection!
+  revisions(first: Int = 50, after: String, where: JSON): DataModelRevisionConnection!
+  releases(first: Int = 50, after: String, where: JSON): DataModelReleaseConnection!
   latestRevision: DataModelRevision
   latestRelease: DataModelRelease
 }
@@ -123,8 +123,21 @@ type DataModelKindOptions {
 }
 
 extend type Query {
-  dataModel(id: ID!): DataModel
-  dataModels(first: Int = 50, after: String): DataModelConnection!
+  """
+  List all data models with optional filtering and pagination.
+
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is
+
+  Example:
+  ```json
+  {
+    "name": { "like": "%user%" },
+    "is_enabled": { "eq": true }
+  }
+  ```
+  """
+  dataModels(first: Int = 50, after: String, where: JSON): DataModelConnection!
 }
 
 input CreateDataModelInput {

apps/frontend/app/api/v1/osograph/schema/graphql/data-model.graphql

@@ -11,14 +11,14 @@ type Dataset {
   updatedAt: DateTime!
   creator: User!
   organization: Organization!
-  tables(first: Int = 50, after: String): TableConnection!
+  tables(first: Int = 50, after: String, where: JSON): TableConnection!
 
   """
   The runs for this dataset. For USER_MODEL datasets, each run is related to individual data models.
   FOR DATA_INGESTION datasets, each run is related to individual ingestion jobs.
   For DATA_CONNECTOR datasets, runs are not applicable and this field will be an empty list.
   """
-  runs(first: Int = 50, after: String): RunConnection!
+  runs(first: Int = 50, after: String, where: JSON): RunConnection!
 
   typeDefinition: DatasetTypeDefinition!
 }
@@ -32,7 +32,7 @@ type DataModelDefinition {
   If the dataset is of type USER_MODEL, this field will contain the list of data models
   associated with the dataset. Otherwise it will be an empty list.
   """
-  dataModels(first: Int = 50, after: String): DataModelConnection!
+  dataModels(first: Int = 50, after: String, where: JSON): DataModelConnection!
 }
 
 type DatasetEdge {
@@ -76,24 +76,39 @@ type TableConnection {
 
 extend type Query {
   """
-  List all datasets
+  List all datasets with optional filtering and pagination.
+
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is
+
+  Example:
+  ```json
+  {
+    "name": { "like": "%hello%" },
+    "type": { "eq": "USER_MODEL" }
+  }
+  ```
   """
-  datasets(first: Int = 50, after: String): DatasetConnection!
+  datasets(first: Int = 50, after: String, where: JSON): DatasetConnection!
 
   """
-  Get a dataset by ID
+  Get table column metadata. The where parameter must include:
+  - orgId: Organization ID
+  - catalogName: Catalog name
+  - schemaName: Schema name
+  - tableName: Table name
+
+  Example:
+  ```json
+  {
+    "orgId": { "eq": "org-uuid" },
+    "catalogName": { "eq": "user_iceberg" },
+    "schemaName": { "eq": "ds_schema" },
+    "tableName": { "eq": "my_table" }
+  }
+  ```
   """
-  dataset(id: ID!): Dataset
-
-  """
-  Get table column metadata
-  """
-  datasetTableMetadata(
-    orgId: ID!
-    catalogName: String!
-    schemaName: String!
-    tableName: String!
-  ): [TableColumn!]!
+  tables(where: JSON!): [TableColumn!]!
 }
 
 extend type Mutation {

apps/frontend/app/api/v1/osograph/schema/graphql/dataset.graphql

@@ -26,14 +26,20 @@ type InvitationConnection {
 
 extend type Query {
   """
-  Get an invitation by ID
-  """
-  invitation(id: ID!): Invitation
+  List all invitations with optional filtering and pagination.
 
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is
+
+  Example:
+  ```json
+  {
+    "status": { "eq": "PENDING" },
+    "email": { "ilike": "%@example.com" }
+  }
+  ```
   """
-  List invitations for current user
-  """
-  myInvitations(first: Int = 50, after: String): InvitationConnection!
+  invitations(first: Int = 50, after: String, where: JSON): InvitationConnection!
 }
 
 extend type Mutation {

apps/frontend/app/api/v1/osograph/schema/graphql/invitation.graphql

@@ -24,14 +24,24 @@ type NotebookConnection {
 
 extend type Query {
   """
-  List all notebooks
-  """
-  notebooks(first: Int = 50, after: String): NotebookConnection!
+  Query notebooks with optional filtering and pagination.
 
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is.
+
+  Example:
+  ```json
+  {
+    "notebook_name": { "like": "%churn%" },
+    "created_at": { "gte": "2024-01-01T00:00:00Z" }
+  }
+  ```
   """
-  Get a notebook by ID
-  """
-  notebook(id: ID!): Notebook
+  notebooks(
+    where: JSON
+    first: Int = 50
+    after: String
+  ): NotebookConnection!
 }
 
 extend type Mutation {

apps/frontend/app/api/v1/osograph/schema/graphql/notebook.graphql

@@ -5,9 +5,9 @@ type Organization {
   description: String
   createdAt: DateTime!
   updatedAt: DateTime!
-  members(first: Int = 50, after: String): UserConnection!
-  notebooks(first: Int = 50, after: String): NotebookConnection!
-  datasets(first: Int = 50, after: String): DatasetConnection!
+  members(first: Int = 50, after: String, where: JSON): UserConnection!
+  notebooks(first: Int = 50, after: String, where: JSON): NotebookConnection!
+  datasets(first: Int = 50, after: String, where: JSON): DatasetConnection!
 }
 
 type OrganizationMember {
@@ -32,14 +32,24 @@ type OrganizationConnection {
 
 extend type Query {
   """
-  List all organizations
-  """
-  organizations(first: Int = 50, after: String): OrganizationConnection!
+  Query organizations with optional filtering and pagination.
 
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is
+
+  Example:
+  ```json
+  {
+    "name": { "like": "%oso%" },
+    "created_at": { "gte": "2024-01-01T00:00:00Z" }
+  }
+  ```
   """
-  Get an organization by ID or name
-  """
-  organization(id: ID, name: String): Organization
+  organizations(
+    where: JSON
+    first: Int = 50
+    after: String
+  ): OrganizationConnection!
 }
 
 extend type Mutation {

apps/frontend/app/api/v1/osograph/schema/graphql/organization.graphql

@@ -58,9 +58,20 @@ type RunConnection {
 
 extend type Query {
   """
-  Get a run by ID
+  List all runs with optional filtering and pagination.
+
+  The where parameter accepts a JSON object with field-level filtering.
+  Each field can have comparison operators: eq, neq, gt, gte, lt, lte, in, like, ilike, is
+
+  Example:
+  ```json
+  {
+    "status": { "eq": "RUNNING" },
+    "datasetId": { "eq": "dataset-uuid" }
+  }
+  ```
   """
-  run(id: ID!): Run
+  runs(first: Int = 50, after: String, where: JSON): RunConnection!
 }
 
 extend type Mutation {

apps/frontend/app/api/v1/osograph/schema/graphql/scheduler.graphql

@@ -4,7 +4,7 @@ type User {
   fullName: String
   avatarUrl: String
   role: String!
-  organizations(first: Int = 50, after: String): OrganizationConnection!
+  organizations(first: Int = 50, after: String, where: JSON): OrganizationConnection!
 }
 
 type UserEdge {
@@ -26,11 +26,11 @@ type Viewer {
   email: String!
   fullName: String
   avatarUrl: String
-  organizations(first: Int = 50, after: String): OrganizationConnection!
-  notebooks(first: Int = 50, after: String): NotebookConnection!
-  datasets(first: Int = 50, after: String): DatasetConnection!
-  invitations(first: Int = 50, after: String): InvitationConnection!
-  runs(first: Int = 50, after: String): RunConnection!
+  organizations(first: Int = 50, after: String, where: JSON): OrganizationConnection!
+  notebooks(first: Int = 50, after: String, where: JSON): NotebookConnection!
+  datasets(first: Int = 50, after: String, where: JSON): DatasetConnection!
+  invitations(first: Int = 50, after: String, where: JSON): InvitationConnection!
+  runs(first: Int = 50, after: String, where: JSON): RunConnection!
 }
 
 extend type Query {