diff --git a/docs/internals.rst b/docs/internals.rst index 7d607bfe..f1064b8b 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -903,6 +903,113 @@ Adds a new metadata entry for the specified column. Any previous column-level metadata entry with the same ``key`` will be overwritten. Internally upserts the value into the the ``metadata_columns`` table inside the :ref:`internal database `. +.. _datasette_column_types: + +Column types +------------ + +Column types are stored in the ``column_types`` table in the :ref:`internal database `. The following methods provide the API for reading and modifying column type assignments. + +.. _datasette_get_column_type: + +await .get_column_type(database, resource, column) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``database`` - string + The name of the database. +``resource`` - string + The name of the table or view. +``column`` - string + The name of the column. + +Returns a ``(column_type_name, config)`` tuple for the specified column. ``column_type_name`` is a string like ``"email"`` or ``"url"``, and ``config`` is a dict or ``None``. If no column type is assigned, returns ``(None, None)``. + +.. code-block:: python + + ct_name, config = await datasette.get_column_type( + "mydb", "mytable", "email_col" + ) + +.. _datasette_get_column_types: + +await .get_column_types(database, resource) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``database`` - string + The name of the database. +``resource`` - string + The name of the table or view. + +Returns a dictionary mapping column names to ``(column_type_name, config)`` tuples for all columns that have assigned types on the given resource. + +.. code-block:: python + + ct_map = await datasette.get_column_types( + "mydb", "mytable" + ) + # {"email_col": ("email", None), "site": ("url", None)} + +.. _datasette_set_column_type: + +await .set_column_type(database, resource, column, column_type, config=None) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``database`` - string + The name of the database. +``resource`` - string + The name of the table or view. +``column`` - string + The name of the column. +``column_type`` - string + The column type name to assign, e.g. ``"email"``. +``config`` - dict, optional + Optional configuration dict for the column type. + +Assigns a column type to a column. Overwrites any existing assignment for that column. + +.. code-block:: python + + await datasette.set_column_type( + "mydb", "mytable", "location", "point", + config={"srid": 4326} + ) + +.. _datasette_remove_column_type: + +await .remove_column_type(database, resource, column) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``database`` - string + The name of the database. +``resource`` - string + The name of the table or view. +``column`` - string + The name of the column. + +Removes the column type assignment for the specified column. + +.. code-block:: python + + await datasette.remove_column_type( + "mydb", "mytable", "location" + ) + +.. _datasette_get_column_type_class: + +.get_column_type_class(column_type_name) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``column_type_name`` - string + The name of the column type, e.g. ``"email"``. + +Returns the registered ``ColumnType`` instance for the given name, or ``None`` if no plugin has registered a column type with that name. This is a synchronous method. + +.. code-block:: python + + ct = datasette.get_column_type_class("email") + if ct: + print(ct.description) # "Email address" + .. _datasette_add_database: .add_database(db, name=None, route=None)