diff --git a/daft/sql/sql.py b/daft/sql/sql.py index cb4ccd7114..b60552ffbe 100644 --- a/daft/sql/sql.py +++ b/daft/sql/sql.py @@ -38,6 +38,55 @@ def _copy_from(self, other: "SQLCatalog") -> None: @PublicAPI def sql_expr(sql: str) -> Expression: + """Parses a SQL string into a Daft Expression + + This function allows you to create Daft Expressions from SQL snippets, which can then be used + in Daft operations or combined with other Daft Expressions. + + Args: + sql (str): A SQL string to be parsed into a Daft Expression. + + Returns: + Expression: A Daft Expression representing the parsed SQL. + + Examples: + Create a simple SQL expression: + + >>> import daft + >>> expr = daft.sql_expr("1 + 2") + >>> print(expr) + lit(1) + lit(2) + + Use SQL expression in a Daft DataFrame operation: + + >>> df = daft.from_pydict({"a": [1, 2, 3], "b": [4, 5, 6]}) + >>> df = df.with_column("c", daft.sql_expr("a + b")) + >>> df.show() + ╭───────┬───────┬───────╮ + │ a ┆ b ┆ c │ + │ --- ┆ --- ┆ --- │ + │ Int64 ┆ Int64 ┆ Int64 │ + ╞═══════╪═══════╪═══════╡ + │ 1 ┆ 4 ┆ 5 │ + ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤ + │ 2 ┆ 5 ┆ 7 │ + ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌┤ + │ 3 ┆ 6 ┆ 9 │ + ╰───────┴───────┴───────╯ + + `daft.sql_expr` is also called automatically for you in some DataFrame operations such as filters: + + >>> df = daft.from_pydict({"x": [1, 2, 3], "y": [4, 5, 6]}) + >>> result = df.where("x < 3 AND y > 4") + >>> result.show() + ╭───────┬───────╮ + │ x ┆ y │ + │ --- ┆ --- │ + │ Int64 ┆ Int64 │ + ╞═══════╪═══════╡ + │ 2 ┆ 5 │ + ╰───────┴───────╯ + """ return Expression._from_pyexpr(_sql_expr(sql)) diff --git a/docs/source/conf.py b/docs/source/conf.py index 7dbe36f417..c5ba1fbe0a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -92,8 +92,8 @@ "user_guide/basic_concepts/introduction": "user_guide/basic_concepts", "user_guide/daft_in_depth/aggregations": "user_guide/aggregations", "user_guide/daft_in_depth/dataframe-operations": "user_guide/dataframe-operations", - "user_guide/datatypes": "user_guide/datatypes", - "user_guide/udf": "user_guide/udf", + "user_guide/daft_in_depth/datatypes": "user_guide/datatypes", + "user_guide/daft_in_depth/udf": "user_guide/udf", } # Resolving code links to github