From faedf951e41e937da952f0c17c0d912af85dfa2f Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Sat, 12 Dec 2020 21:40:18 -0800 Subject: [PATCH] table.analyze_column() documentation --- docs/python-api.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/python-api.rst b/docs/python-api.rst index 8dead7d..130c4cb 100644 --- a/docs/python-api.rst +++ b/docs/python-api.rst @@ -747,6 +747,41 @@ You can inspect the database to see the results like this:: PRIMARY KEY ([characteristics_id], [dogs_id]) ) +.. _python_api_analyze_column: + +Analyzing a column +================== + +The ``table.analyze_column(column, common_limit=10, value_truncate=None)`` method is used by the :ref:`analyze-tables ` CLI command. It returns a ``ColumnDetails`` named tuple with the following fields: + +``table`` + The name of the table + +``column`` + The name of the column + +``total_rows`` + The total number of rows in the table` + +``num_null`` + The number of rows for which this column is null + +``num_blank`` + The number of rows for which this column is blank (the empty string) + +``num_distinct`` + The number of distinct values in this column + +``most_common`` + The ``N`` most common values as a list of ``(value, count)`` tuples`, or ``None`` if the table consists entirely of distinct values + +``least_common`` + The ``N`` least common values as a list of ``(value, count)`` tuples`, or ``None`` if the table is entirely distinct or if the number of distinct values is less than N (since they will already have been returned in ``most_common``) + +``N`` defaults to 10, or you can pass a custom ``N`` using the ``common_limit`` parameter. + +You can use the ``value_truncate`` parameter to truncate values in the ``most_common`` and ``least_common`` lists to a specified number of characters. + .. _python_api_add_column: Adding columns