Parses a query string and applies it as a WHERE clause to the given queryable.

Supports dotted identifiers (e.g., author.name) that automatically resolve to left joins on schema associations, or to JSONB path extraction when the first segment refers to a :map field on the schema.

JSONB column support

When a dotted identifier like metadata.key is used and the schema defines metadata as a :map field, the builder uses json_extract_path/2 instead of creating a join. Nested paths like metadata.nested.key are supported.

To enable type casting on JSON values (essential for numeric/boolean comparisons), use the keyword list format for :allowed_fields.

Options

• :allowed_fields - controls which fields are permitted. Supports two formats:

  • Plain list (access control only): [:name, :age, :"metadata.key"]
  • Keyword list (access control + type casting): [name: :string, metadata: :map, "metadata.key": :string, "metadata.age": :integer]

  When the keyword format provides a type for a JSON sub-path, the result is wrapped with type/2 for proper casting. Without type info, raw json_extract_path is used.

  Dotted paths use atom notation (e.g., :"author.name").

• Schemaless queries — when using a string table name (e.g., from("posts")), associations can be defined directly in allowed_fields using {:assoc, opts} tuples:

  allowed_fields: [
    name: :string,
    author: {:assoc,
      table: "users",
      owner_key: :author_id,
      related_key: :id,
      fields: [name: :string, email: :string]}
  ]

  Association options:

  • :table — target table name (string, required)
  • :owner_key — FK on the source table (atom, required)
  • :related_key — PK on the target table (atom, required)
  • :fields — keyword list of available fields, supports nesting (optional, defaults to [] meaning all fields allowed)

  When a schema IS available, it takes priority (fully backward compatible).

Returns {:ok, query} or {:error, reason}.

See EctoQueryParser.Parser.parse/1.