added docs for JSON, JSONB, and the arrow function

Author: dantownsend

docs/src/piccolo/schema/column_types.rst

@@ -134,3 +134,56 @@ Timestamp
 =========
 
 .. autoclass:: Timestamp
+
+-------------------------------------------------------------------------------
+
+****
+JSON
+****
+
+Storing JSON can be useful in certain situations, for example - raw API
+responses, data from a Javascript app, and for storing data with an unknown or
+changing schema.
+
+====
+JSON
+====
+
+.. autoclass:: JSON
+
+=====
+JSONB
+=====
+
+.. autoclass:: JSONB
+
+arrow
+=====
+
+``JSONB`` columns have an ``arrow`` function, which is useful for retrieving
+a subset of the JSON data, and for filtering in a where clause.
+
+.. code-block:: python
+
+    # Example schema:
+    class Booking(Table):
+        data = JSONB()
+
+    Booking.create_table().run_sync()
+
+    # Example data:
+    Booking.insert(
+        Booking(data='{"name": "Alison"}'),
+        Booking(data='{"name": "Bob"}')
+    ).run_sync()
+
+    # Example queries
+    >>> Booking.select(
+    >>>     Booking.id, Booking.data.arrow('name').as_alias('name')
+    >>> ).run_sync()
+    [{'id': 1, 'name': '"Alison"'}, {'id': 2, 'name': '"Bob"'}]
+
+    >>> Booking.select(Booking.id).where(
+    >>>     Booking.data.arrow('name') == '"Alison"'
+    >>> ).run_sync()
+    [{'id': 1}]

piccolo/columns/__init__.py

@@ -1,10 +1,12 @@
-from .column_types import (  # noqa
+from .column_types import (  # noqa: F401
     Boolean,
     Decimal,
     Float,
     ForeignKey,
     Integer,
     Interval,
+    JSON,
+    JSONB,
     Numeric,
     PrimaryKey,
     Real,
@@ -15,6 +17,6 @@
     UUID,
     Varchar,
 )
-from .base import Column, ForeignKeyMeta, Selectable  # noqa
-from .base import OnDelete, OnUpdate  # noqa
-from .combination import And, Or, Where  # noqa
+from .base import Column, ForeignKeyMeta, Selectable  # noqa: F401
+from .base import OnDelete, OnUpdate  # noqa: F401
+from .combination import And, Or, Where  # noqa: F401

piccolo/columns/column_types.py

@@ -1046,9 +1046,13 @@ def __getattribute__(self, name: str):
 
 class JSON(Column):  # lgtm[py/missing-equals]
     """
-    Used for storing JSON strings. In Postgres, the JSON can be queried
-    directly. The data is stored as a string. This is preferable to JSONB
-    if you just want to store and retrieve JSON without querying it directly.
+    Used for storing JSON strings. The data is stored as text. This can be
+    preferable to JSONB if you just want to store and retrieve JSON without
+    querying it directly. It works with SQLite and Postgres.
+
+    :param default:
+        Either a JSON string can be provided, or a Python ``dict`` or ``list``
+        which is then converted to a JSON string.
 
     """
 
@@ -1079,13 +1083,14 @@ def __init__(
 
 class JSONB(JSON):
     """
-    Used for storing JSON strings. In Postgres, the JSON can be queried
-    directly. The data is stored in a binary format, which makes querying
-    faster, but insertion and retrieval slower (as it needs to be converted
-    to and from the binary format).
+    Used for storing JSON strings - Postgres only. The data is stored in a
+    binary format, and can be queried. Insertion can be slower (as it needs to
+    be converted to the binary format). The benefits of JSONB generally
+    outweigh the downsides.
+
     """
 
-    def arrow(self, key: str) -> JSON:
+    def arrow(self, key: str) -> JSONB:
         """
         Allows part of the JSON structure to be returned - for example,
         for {"a": 1}, and a key value of "a", then 1 will be returned.