docs: add enums to working with data types how-to

docs/how-tos/working-with-postgresql-data-types.rst

@@ -11,6 +11,8 @@ PostgREST makes use of PostgreSQL string representations to work with data types
  :local:
  :depth: 1
 
+.. NOTE: Titles are ordered alphabetically. New entries should respect this order.
+
 Arrays
 ------
 
@@ -198,6 +200,52 @@ Or you could insert the same data in JSON format.
 
 You can also query the data using arrow operators. See :ref:`composite_array_columns`.
 
+Enums
+-----
+
+You can handle `Enumerated Types <https://www.postgresql.org/docs/current/datatype-enum.html>`_ using string representations:
+
+.. code-block:: postgres
+
+ create type letter_size as enum ('s','m','l','xl');
+
+ create table products (
+ id int primary key generated always as identity,
+ name text,
+ size letter_size
+ );
+
+To insert or update the value use a string:
+
+.. code-block:: bash
+
+ curl -X POST "http://localhost:3000/products" \
+ -H "Content-Type: application/json" \
+ -d @- << EOF
+ { "name": "t-shirt", "size": "l" }
+ EOF
+
+You can then query and filter the enum using the compatible :ref:`operators <operators>`.
+For example, to get all the products larger than `m` and ordering them by their size:
+
+.. code-block:: bash
+
+ curl "http://localhost:3000/products?select=name,size&size=gt.m&order=size"
+
+.. code-block:: json
+
+ [
+ {
+ "name": "t-shirt",
+ "size": "l"
+ },
+ {
+ "name": "hoodie",
+ "size": "xl"
+ }
+ ]
+
+
 hstore
 ------
 

docs/postgrest.dict

@@ -28,6 +28,8 @@ DDL
 DOM
 DevOps
 dockerize
+enum
+Enums
 eq
 ETH
 Ethereum