diff --git a/py-polars/docs/source/reference/sql/functions/index.rst b/py-polars/docs/source/reference/sql/functions/index.rst index 607e720956a3..cf6247e41a10 100644 --- a/py-polars/docs/source/reference/sql/functions/index.rst +++ b/py-polars/docs/source/reference/sql/functions/index.rst @@ -85,3 +85,11 @@ SQL Functions trigonometry .. grid-item-card:: + + **Types** + ^^^^^^^^^ + + .. toctree:: + :maxdepth: 2 + + types diff --git a/py-polars/docs/source/reference/sql/functions/types.rst b/py-polars/docs/source/reference/sql/functions/types.rst new file mode 100644 index 000000000000..d22a1153a1b9 --- /dev/null +++ b/py-polars/docs/source/reference/sql/functions/types.rst @@ -0,0 +1,90 @@ +Types +===== + +.. list-table:: + :header-rows: 1 + :widths: 20 60 + + * - Function + - Description + * - :ref:`CAST ` + - Convert a value to a different datatype. + * - :ref:`TRY_CAST ` + - Convert a value to a different datatype, returning NULL if the conversion fails. + + +.. _cast: + +CAST +---- +Convert a value to a different datatype. + +Note that the more compact PostgreSQL `::type` syntax is also supported. + +**Example:** + +.. code-block:: python + + df = pl.DataFrame( + { + "foo": [20, 10, 30], + "bar": ["1999-12-31", "2012-07-05", "2024-01-01"], + } + ) + df.sql(""" + SELECT + foo::float4, + bar::date + FROM self + """) + # shape: (3, 2) + # ┌──────┬────────────┐ + # │ foo ┆ bar │ + # │ --- ┆ --- │ + # │ f32 ┆ date │ + # ╞══════╪════════════╡ + # │ 20.0 ┆ 1999-12-31 │ + # │ 10.0 ┆ 2012-07-05 │ + # │ 30.0 ┆ 2024-01-01 │ + # └──────┴────────────┘ + + +.. _try_cast: + +TRY_CAST +-------- +Convert a value to a different datatype, returning `NULL` if the conversion fails. + +**Example:** + +.. code-block:: python + + df = pl.DataFrame( + { + "foo": [65432, 101010, -33333], + "bar": ["1999-12-31", "N/A", "2024-01-01"], + } + ) + df.sql(""" + SELECT + TRY_CAST(foo AS uint2), + TRY_CAST(bar AS date) + FROM self + """) + # shape: (3, 2) + # ┌───────┬────────────┐ + # │ foo ┆ bar │ + # │ --- ┆ --- │ + # │ u16 ┆ date │ + # ╞═══════╪════════════╡ + # │ 65432 ┆ 1999-12-31 │ + # │ 10101 ┆ null │ + # │ null ┆ 2024-01-01 │ + # └───────┴────────────┘ + +Note that with a regular `CAST` this would fail with the following error: + +.. code-block:: + + InvalidOperationError: + conversion from `i64` to `u16` failed in column 'foo' for 1 out of 3 values: [-33333]