CITEXT data type

Author: taroface

src/current/v25.3/citext.md

@@ -0,0 +1,122 @@
+---
+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 %}) stores case-insensitive strings.
+
+All `CITEXT` values are folded to lowercase before comparison. This is handled internally with the [`lower()`]({% link {{ page.version.version }}/functions-and-operators.md %}#string-and-byte-functions) function.
+
+For example, the following comparison evaluates to `true`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT 'Roach'::CITEXT = 'roach'::CITEXT;
+~~~
+
+~~~
+  ?column?
+------------
+     t
+~~~
+
+With `CITEXT`, equality operators (`=`, `!=`, `<>`), ordering operators (`<`, `>`, etc.), and [`STRING` functions]({% link {{ page.version.version }}/functions-and-operators.md %}#string-and-byte-functions), treat values as case-insensitive by default. Refer to the [example](#example).
+
+Aside from comparisons, `CITEXT` behaves like [`STRING`]({% link {{ page.version.version }}/string.md %}).
+
+## 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 are folded to lowercase on every comparison, `CITEXT` columns and indexes consume marginally more CPU and memory than their `STRING` equivalents, especially on write-heavy workloads.
+
+## Collations
+
+`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. If you need accent-insensitive behavior, consider using `STRING` with a nondeterministic collation instead.
+
+## 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'),
+('juno', 'juno@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';
+~~~
+
+~~~
+  name  |       email
+--------+--------------------
+  roach | roach@example.com
+(1 row)
+~~~
+
+An ordering comparison is also case-insensitive with `CITEXT`. In the following eaxmple, `'Xavi'` is folded to lowercase before the comparison:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT username FROM logins WHERE username < 'Xavi';
+~~~
+
+~~~ 
+  username
+------------
+  roach
+  juno
+(2 rows)
+~~~
+
+For case-sensitive comparisons on `CITEXT` values, cast to `STRING` explicitly. In the default Unicode ordering, the uppercase value is considered less than the lowercase values in the table:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT username FROM logins WHERE username::STRING < 'Xavi';
+~~~
+
+~~~
+  username | email
+-----------+--------
+(0 rows)
+~~~
+
+## Supported casting and conversion
+
+`CITEXT` values can be [cast]({% link {{ page.version.version }}/data-types.md %}#data-type-conversions-and-casts) to the following data types:
+
+Type | Details
+-----|--------
+`STRING` | Preserves case information when casting to `STRING`.
+
+## See also
+
+- [`STRING`]({% link {{ page.version.version }}/string.md %})
+- [Data Types]({% link {{ page.version.version }}/data-types.md %})
+- [`COLLATE`]({% link {{ page.version.version }}/collate.md %})

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`

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'`.