diff --git a/src/current/_includes/v25.3/sidebar-data/sql.json b/src/current/_includes/v25.3/sidebar-data/sql.json index 8759eae97e6..e2bd29ee86e 100644 --- a/src/current/_includes/v25.3/sidebar-data/sql.json +++ b/src/current/_includes/v25.3/sidebar-data/sql.json @@ -1004,6 +1004,12 @@ "/${VERSION}/bytes.html" ] }, + { + "title": "CITEXT", + "urls": [ + "/${VERSION}/citext.html" + ] + }, { "title": "COLLATE", "urls": [ diff --git a/src/current/v25.3/citext.md b/src/current/v25.3/citext.md new file mode 100644 index 00000000000..3f91ae6429b --- /dev/null +++ b/src/current/v25.3/citext.md @@ -0,0 +1,98 @@ +--- +title: CITEXT +summary: The CITEXT data type stores case-insensitive text values. +toc: true +docs_area: reference.sql +--- + +The `CITEXT` [data type]({% link {{ page.version.version }}/data-types.md %}) represents a case-insensitive string. Like `STRING` values, `CITEXT` values preserve their casing when stored and retrieved. Unlike `STRING` values, comparisons between `CITEXT` values are case-insensitive for all [Unicode characters](https://en.wikipedia.org/wiki/List_of_Unicode_characters) that have a defined uppercase/lowercase mapping (e.g., `'É' = 'é'`). + +Equality operators (`=`, `!=`, `<>`) and ordering operators (`<`, `>`, etc.) treat `CITEXT` values as case-insensitive by default. Refer to the [example](#example). + +{{site.data.alerts.callout_success}} +`CITEXT` compares values as a `STRING` column with the `und-u-ks-level2` [collation]({% link {{ page.version.version }}/collate.md %}), meaning it is case-insensitive but accent-sensitive. +{{site.data.alerts.end}} + +## Syntax + +To declare a `CITEXT` column, use the type name directly in your `CREATE TABLE` statement: + +{% include_cached copy-clipboard.html %} +~~~ sql +CREATE TABLE logins ( + name CITEXT PRIMARY KEY, + email TEXT NOT NULL +); +~~~ + +## Size + +As with `STRING`, `CITEXT` values should be kept below 64 KB for best performance. Because `CITEXT` values resort to a collation engine on every comparison, `CITEXT` columns and indexes consume marginally more CPU and memory than their `STRING` equivalents. + +## Example + +Create and populate a table: + +{% include_cached copy-clipboard.html %} +~~~ sql +CREATE TABLE logins ( + username CITEXT, + email STRING +); +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +INSERT INTO logins VALUES +('Roach', 'Roach@example.com'), +('lincoln', 'lincoln@example.com'); +~~~ + +Because `CITEXT` comparisons are case-insensitive, an equality predicate matches regardless of letter case: + +{% include_cached copy-clipboard.html %} +~~~ sql +SELECT * FROM logins WHERE username = 'roach'; +~~~ + +~~~ + username | email +-----------+-------------------- + Roach | Roach@example.com +(1 row) +~~~ + +An ordering comparison is also case-insensitive with `CITEXT`: + +{% include_cached copy-clipboard.html %} +~~~ sql +SELECT username FROM logins WHERE username < 'Xavi'; +~~~ + +~~~ + username +------------ + Roach + lincoln +(2 rows) +~~~ + +For case-sensitive comparisons on `CITEXT` values, cast to `STRING` explicitly. In the default Unicode ordering, an uppercase value is considered less than the lowercase value in the table: + +{% include_cached copy-clipboard.html %} +~~~ sql +SELECT username FROM logins WHERE username::STRING < 'Xavi'; +~~~ + +~~~ + username +------------ + Roach +(1 row) +~~~ + +## See also + +- [Data Types]({% link {{ page.version.version }}/data-types.md %}) +- [`STRING`]({% link {{ page.version.version }}/string.md %}) +- [`COLLATE`]({% link {{ page.version.version }}/collate.md %}) \ No newline at end of file diff --git a/src/current/v25.3/data-types.md b/src/current/v25.3/data-types.md index ab14f2bee51..b198a07c886 100644 --- a/src/current/v25.3/data-types.md +++ b/src/current/v25.3/data-types.md @@ -16,6 +16,7 @@ Type | Description | Example [`BOOL`]({% link {{ page.version.version }}/bool.md %}) | A Boolean value. | `true` [`BYTES`]({% link {{ page.version.version }}/bytes.md %}) | A string of binary characters. | `b'\141\061\142\062\143\063'` [`COLLATE`]({% link {{ page.version.version }}/collate.md %}) | The `COLLATE` feature lets you sort [`STRING`]({% link {{ page.version.version }}/string.md %}) values according to language- and country-specific rules, known as collations. | `'a1b2c3' COLLATE en` +[`CITEXT`]({% link {{ page.version.version }}/citext.md %}) | Case-insensitive text. | `'Roach'` [`DATE`]({% link {{ page.version.version }}/date.md %}) | A date. | `DATE '2016-01-25'` [`ENUM`]({% link {{ page.version.version }}/enum.md %}) | A user-defined data type comprised of a set of static values. | `ENUM ('club, 'diamond', 'heart', 'spade')` [`DECIMAL`]({% link {{ page.version.version }}/decimal.md %}) | An exact, fixed-point number. | `1.2345` diff --git a/src/current/v25.3/string.md b/src/current/v25.3/string.md index 7fea14d9eca..ee7964b4723 100644 --- a/src/current/v25.3/string.md +++ b/src/current/v25.3/string.md @@ -135,6 +135,7 @@ Type | Details `BIT` | Requires supported [`BIT`]({% link {{ page.version.version }}/bit.md %}) string format, e.g., `'101001'` or `'xAB'`. `BOOL` | Requires supported [`BOOL`]({% link {{ page.version.version }}/bool.md %}) string format, e.g., `'true'`. `BYTES` | For more details, [see here]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). +`CITEXT` | Preserves the original letter case, but value comparisons are treated case-insensitively. Refer to [`CITEXT`]({% link {{ page.version.version }}/citext.md %}). `DATE` | Requires supported [`DATE`]({% link {{ page.version.version }}/date.md %}) string format, e.g., `'2016-01-25'`. `DECIMAL` | Requires supported [`DECIMAL`]({% link {{ page.version.version }}/decimal.md %}) string format, e.g., `'1.1'`. `FLOAT` | Requires supported [`FLOAT`]({% link {{ page.version.version }}/float.md %}) string format, e.g., `'1.1'`.