From 0f45a9cdd0dd27c5b48e9f37b53375ad4a222880 Mon Sep 17 00:00:00 2001
From: Laurence Isla <lau.isla.c@gmail.com>
Date: Thu, 29 Feb 2024 14:19:42 -0500
Subject: [PATCH] docs: add enums to working with data types how-to

---
 .../working-with-postgresql-data-types.rst    | 45 +++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/how-tos/working-with-postgresql-data-types.rst b/docs/how-tos/working-with-postgresql-data-types.rst
index ce1e1772176..d21a0c6019f 100644
--- a/docs/how-tos/working-with-postgresql-data-types.rst
+++ b/docs/how-tos/working-with-postgresql-data-types.rst
@@ -561,3 +561,48 @@ You can use other comparative filters and also all the `PostgreSQL special date/
       "due_date": "2022-02-27T06:00:00-05:00"
     }
   ]
+
+Enums
+-----
+
+You can handle :ref:`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-bloc:: 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"
+    }
+  ]