diff --git a/usage/sync-rules/operators-and-functions.mdx b/usage/sync-rules/operators-and-functions.mdx index aaa9dd9f..f69764c1 100644 --- a/usage/sync-rules/operators-and-functions.mdx +++ b/usage/sync-rules/operators-and-functions.mdx @@ -17,38 +17,39 @@ Some fundamental restrictions on these operators and functions are: ### Operators -| Category | Operators | Notes | -| ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| Comparison | `= != < > <= >=` | If either parameter is null, this evaluates to null. | -| Null | `IS NULL`, `IS NOT NULL` | | -| Mathematical | `+ - * /` | | -| Logical | `AND`, `OR`, `NOT` | | -| Cast | `CAST(x AS type)`
`x :: type` | Cast to text, numeric, integer, real or blob. | -| JSON | `json -> 'path'`
`json ->> 'path'` | `->` Returns the value as a JSON string.
`->>` Returns the extracted value. | -| Text concatenation | `\|\|` | Joins two text values together. | -| Arrays | ` IN ` | Returns true if the `left` value is present in the `right` JSON array. In data queries, only the `left` value may be a bucket parameter. In parameter queries, the `left` or `right` value may be a bucket parameter. Differs from the SQLite operator in that it can be used directly on a JSON array. | +| Category | Operators | Example | Notes | +| ------------------ | ----------------------------------------------------------- | ----------------------------------------------------------- | ------------------------ | +| Comparison | `= != < > <= >=` | `SELECT * FROM todos WHERE priority >= 2` | If either parameter is null, this evaluates to null. | +| Null | `IS NULL`, `IS NOT NULL` | `SELECT * FROM todos WHERE completed_at IS NOT NULL` | | +| Mathematical | `+ - * /` | `SELECT *, priority * 10 as weighted_priority FROM todos` | | +| Logical | `AND`, `OR`, `NOT` | `SELECT * FROM todos WHERE is_active AND priority >= 2` | | +| Cast | `CAST(x AS type)`
`x :: type` | `SELECT CAST(list_id AS text) FROM todos` | Cast to text, numeric, integer, real or blob. | +| JSON | `json -> 'path'`
`json ->> 'path'` | `SELECT metadata -> 'tags' ->> 'category' FROM todos` | `->` Returns the value as a JSON string.
`->>` Returns the extracted value. | +| Text concatenation | `\|\|` | `SELECT title \|\| ' - ' \|\| description as full_text FROM todos` | Joins text values. | +| Arrays | ` IN ` | `SELECT * FROM lists WHERE type IN ['personal', 'work']` | Returns true if the `left` value is present in the `right` JSON array. In data queries, only the `left` value may be a bucket parameter. In parameter queries, the `left` or `right` value may be a bucket parameter. Differs from the SQLite operator in that it can be used directly on a JSON array. | ### Functions -| Function | Description | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [upper(text)](https://www.sqlite.org/lang_corefunc.html#upper) | Convert text to upper case. | -| [lower(text)](https://www.sqlite.org/lang_corefunc.html#lower) | Convert text to lower case. | -| [substring(text, start, length)](https://sqlite.org/lang_corefunc.html#substr) | Extracts a portion of a string based on specified start index and length. Start index is 1-based. | -| [hex(data)](https://www.sqlite.org/lang_corefunc.html#hex) | Convert blob or text data to hexadecimal text. | -| base64(data) | Convert blob or text data to base64 text. | -| [length(data)](https://www.sqlite.org/lang_corefunc.html#length) | For text, return the number of characters. For blob, return the number of bytes. For null, return null. For integer and real, convert to text and return the number of characters. | -| [typeof(data)](https://www.sqlite.org/lang_corefunc.html#typeof) | text, integer, real, blob or null | -| [json\_extract(data, path)](https://www.sqlite.org/json1.html#jex) | Same as `->>` operator, but the path must start with `$.` | -| [json\_array\_length(data)](https://www.sqlite.org/json1.html#jarraylen) | Given a JSON array (as text), returns the length of the array. If data is null, returns null. If the value is not a JSON array, returns 0. | -| [json\_valid(data)](https://www.sqlite.org/json1.html#jvalid) | Returns 1 if the data can be parsed as JSON, 0 otherwise. | -| json\_keys(data) | Returns the set of keys of a JSON object as a JSON array. | -| [ifnull(x,y)](https://www.sqlite.org/lang_corefunc.html#ifnull) | Returns x if non-null, otherwise returns y. | -| [unixepoch(datetime, \[modifier\])](https://www.sqlite.org/lang_datefunc.html) | Returns a datetime as Unix timestamp. If modifier is "subsec", the result is a floating point number, with milliseconds including in the fraction. The datetime argument is required - this function cannot be used to get the current time. | -| [datetime(datetime, \[modifier\])](https://www.sqlite.org/lang_datefunc.html) | Returns a datetime as a datetime string, in the format YYYY-MM-DD HH:MM:SS. If the specifier is "subsec", milliseconds are also included. If the modifier is "unixepoch", the argument is interpreted as a unix timestamp. Both modifiers can be included: datetime(timestamp, 'unixepoch', 'subsec'). The datetime argument is required - this function cannot be used to get the current time. | -| [ST\_AsGeoJSON(geometry)](https://postgis.net/docs/ST_AsGeoJSON.html) | Convert [PostGIS](https://postgis.net/) (in Postgres) geometry from WKB to GeoJSON. Combine with JSON operators to extract specific fields. | -| [ST\_AsText(geometry)](https://postgis.net/docs/ST_AsText.html) | Convert [PostGIS](https://postgis.net/) (in Postgres) geometry from WKB to Well-Known Text (WKT). | -| [ST\_X(point)](https://postgis.net/docs/ST_X.html) | Get the X coordinate of a [PostGIS](https://postgis.net/) point (in Postgres) | -| [ST\_Y(point)](https://postgis.net/docs/ST_Y.html) | Get the Y coordinate of a [PostGIS](https://postgis.net/) point (in Postgres) | +| Function | Description | Example | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | +| [upper(text)](https://www.sqlite.org/lang_corefunc.html#upper) | Convert text to upper case. | `SELECT upper(title) as uppercase_title FROM todos WHERE todos.list_id = bucket.list_id` | +| [lower(text)](https://www.sqlite.org/lang_corefunc.html#lower) | Convert text to lower case. | `SELECT lower(category) as lowercase_category FROM lists WHERE lists.id = bucket.list_id` | +| [substring(text, start, length)](https://sqlite.org/lang_corefunc.html#substr) | Extracts a portion of a string based on specified start index and length. Start index is 1-based. | `SELECT substring(description, 1, 100) as preview FROM todos WHERE todos.list_id = bucket.list_id` | +| [hex(data)](https://www.sqlite.org/lang_corefunc.html#hex) | Convert blob or text data to hexadecimal text. | `SELECT hex(attachment_data) as hex_data FROM todos WHERE todos.list_id = bucket.list_id` | +| base64(data) | Convert blob or text data to base64 text. | `SELECT base64(attachment_data) as base64_attachment FROM todos WHERE todos.list_id = bucket.list_id` | +| [length(data)](https://www.sqlite.org/lang_corefunc.html#length) | For text, return the number of characters. For blob, return the number of bytes. For null, return null. For integer and real, convert to text and return the number of characters. | `SELECT *, length(description) as description_length FROM todos WHERE todos.list_id = bucket.list_id` | +| [typeof(data)](https://www.sqlite.org/lang_corefunc.html#typeof) | text, integer, real, blob or null | `SELECT typeof(priority) as priority_type FROM todos WHERE todos.list_id = bucket.list_id` | +| [json\_extract(data, path)](https://www.sqlite.org/json1.html#jex) | Same as `->>` operator, but the path must start with `$.` | `SELECT json_extract(metadata, '$.tags') as tags FROM todos WHERE todos.list_id = bucket.list_id` | +| [json\_array\_length(data)](https://www.sqlite.org/json1.html#jarraylen) | Given a JSON array (as text), returns the length of the array. If data is null, returns null. If the value is not a JSON array, returns 0. | `SELECT json_array_length(subtasks) as subtask_count FROM todos WHERE todos.list_id = bucket.list_id` | +| [json\_valid(data)](https://www.sqlite.org/json1.html#jvalid) | Returns 1 if the data can be parsed as JSON, 0 otherwise. | `SELECT *, json_valid(metadata) as is_valid_json FROM lists WHERE lists.id = bucket.list_id` | +| json\_keys(data) | Returns the set of keys of a JSON object as a JSON array. | `SELECT json_keys(metadata) as metadata_keys FROM todos WHERE todos.list_id = bucket.list_id` | +| [json\_each(data)](https://www.sqlite.org/json1.html#jeach) | Expands a JSON array or object into a set of rows. Each row contains a key and value. | `SELECT value as project_id FROM json_each(request.jwt() -> 'project_ids')` | +| [ifnull(x,y)](https://www.sqlite.org/lang_corefunc.html#ifnull) | Returns x if non-null, otherwise returns y. | `SELECT ifnull(due_date, created_at) as effective_date FROM todos WHERE todos.list_id = bucket.list_id` | +| [unixepoch(datetime, \[modifier\])](https://www.sqlite.org/lang_datefunc.html) | Returns a datetime as Unix timestamp. If modifier is "subsec", the result is a floating point number, with milliseconds including in the fraction. The datetime argument is required - this function cannot be used to get the current time. | `SELECT *, unixepoch(created_at) as unix_timestamp FROM todos WHERE todos.list_id = bucket.list_id` | +| [datetime(datetime, \[modifier\])](https://www.sqlite.org/lang_datefunc.html) | Returns a datetime as a datetime string, in the format YYYY-MM-DD HH:MM:SS. If the specifier is "subsec", milliseconds are also included. If the modifier is "unixepoch", the argument is interpreted as a unix timestamp. Both modifiers can be included: datetime(timestamp, 'unixepoch', 'subsec'). The datetime argument is required - this function cannot be used to get the current time. | `SELECT datetime(due_date, 'unixepoch') as formatted_due_date FROM todos WHERE todos.list_id = bucket.list_id` | +| [ST\_AsGeoJSON(geometry)](https://postgis.net/docs/ST_AsGeoJSON.html) | Convert [PostGIS](https://postgis.net/) (in Postgres) geometry from WKB to GeoJSON. Combine with JSON operators to extract specific fields. | `SELECT ST_AsGeoJSON(location) as location_json FROM lists WHERE lists.id = bucket.list_id` | +| [ST\_AsText(geometry)](https://postgis.net/docs/ST_AsText.html) | Convert [PostGIS](https://postgis.net/) (in Postgres) geometry from WKB to Well-Known Text (WKT). | `SELECT ST_AsText(area) as area_wkt FROM lists WHERE lists.id = bucket.list_id` | +| [ST\_X(point)](https://postgis.net/docs/ST_X.html) | Get the X coordinate of a [PostGIS](https://postgis.net/) point (in Postgres) | `SELECT ST_X(location) as longitude FROM lists WHERE lists.id = bucket.list_id` | +| [ST\_Y(point)](https://postgis.net/docs/ST_Y.html) | Get the Y coordinate of a [PostGIS](https://postgis.net/) point (in Postgres) | `SELECT ST_Y(location) as latitude FROM lists WHERE lists.id = bucket.list_id` | Most of these functions are based on the [built-in SQLite functions](https://www.sqlite.org/lang_corefunc.html) and [SQLite JSON functions](https://www.sqlite.org/json1.html).