Data Functions

param

param(type)

Create a deferred parameter of a given type.

Parameters

Name	Type	Description	Default
type	Union[dt.DataType, str]	The type of the unbound parameter, e.g., double, int64, date, etc.	required

Returns

Name	Type	Description
	Scalar	A scalar expression backend by a parameter

Examples

>>> from datetime import date
>>> import letsql
>>> start = letsql.param("date")
>>> t = letsql.memtable(
...     {
...         "date_col": [date(2013, 1, 1), date(2013, 1, 2), date(2013, 1, 3)],
...         "value": [1.0, 2.0, 3.0],
...     },
... )
>>> expr = t.filter(t.date_col >= start).value.sum()
>>> expr.execute(params={start: date(2013, 1, 1)})
6.0
>>> expr.execute(params={start: date(2013, 1, 2)})
5.0
>>> expr.execute(params={start: date(2013, 1, 3)})
3.0

schema

schema(pairs=None, names=None, types=None)

Validate and return a Schema object.

Parameters

Name	Type	Description	Default
pairs	SchemaLike | None	List or dictionary of name, type pairs. Mutually exclusive with names and types arguments.	None
names	Iterable[str] | None	Field names. Mutually exclusive with pairs.	None
types	Iterable[str | dt.DataType] | None	Field types. Mutually exclusive with pairs.	None

Returns

Name	Type	Description
	Schema	An ibis schema

Examples

>>> from letsql import schema
>>> sc = schema([("foo", "string"), ("bar", "int64"), ("baz", "boolean")])
>>> sc = schema(names=["foo", "bar", "baz"], types=["string", "int64", "boolean"])
>>> sc = schema(dict(foo="string")) # no-op

table

table(schema=None, name=None, catalog=None, database=None)

Create a table literal or an abstract table without data.

Ibis uses the word database to refer to a collection of tables, and the word catalog to refer to a collection of databases. You can use a combination of catalog and database to specify a hierarchical location for table.

Parameters

Name	Type	Description	Default
schema	SchemaLike | None	A schema for the table	None
name	str | None	Name for the table. One is generated if this value is None.	None
catalog	str | None	A collection of database.	None
database	str | None	A collection of tables. Required if catalog is not None.	None

Returns

Name	Type	Description
	Table	A table expression

Examples

Create a table with no data backing it

>>> import letsql
>>> letsql.options.interactive = False
>>> t = letsql.table(schema=dict(a="int", b="string"), name="t")
>>> t
UnboundTable: t
  a int64
  b string

Create a table with no data backing it in a specific location

>>> import letsql
>>> letsql.options.interactive = False
>>> t = letsql.table(schema=dict(a="int"), name="t", catalog="cat", database="db")
>>> t
UnboundTable: cat.db.t
  a int64

memtable

memtable(data, *, columns=None, schema=None, name=None)

Construct an ibis table expression from in-memory data.

Parameters

Name	Type	Description	Default
data		A table-like object (pandas.DataFrame, pyarrow.Table, or polars.DataFrame), or any data accepted by the pandas.DataFrame constructor (e.g. a list of dicts). Note that ibis objects (e.g. MapValue) may not be passed in as part of data and will result in an error. Do not depend on the underlying storage type (e.g., pyarrow.Table), it’s subject to change across non-major releases.	required
columns	Iterable[str] | None	Optional of column names. If provided, must match the number of columns in data.	None
schema	SchemaLike | None	Optional Schema. The functions use data to infer a schema if not passed.	None
name	str | None	Optional name of the table.	None

Returns

Name	Type	Description
	Table	A table expression backed by in-memory data.

Examples

>>> import letsql
>>> letsql.options.interactive = False
>>> t = letsql.memtable([{"a": 1}, {"a": 2}])
>>> t
InMemoryTable
  data:
    PandasDataFrameProxy:
         a
      0  1
      1  2

>>> t = letsql.memtable([{"a": 1, "b": "foo"}, {"a": 2, "b": "baz"}])
>>> t
InMemoryTable
  data:
    PandasDataFrameProxy:
         a    b
      0  1  foo
      1  2  baz

Create a table literal without column names embedded in the data and pass columns

>>> t = letsql.memtable([(1, "foo"), (2, "baz")], columns=["a", "b"])
>>> t
InMemoryTable
  data:
    PandasDataFrameProxy:
         a    b
      0  1  foo
      1  2  baz

Create a table literal without column names embedded in the data. Ibis generates column names if none are provided.

>>> t = letsql.memtable([(1, "foo"), (2, "baz")])
>>> t
InMemoryTable
  data:
    PandasDataFrameProxy:
         col0 col1
      0     1  foo
      1     2  baz

desc

desc(expr)

Create a descending sort key from expr or column name.

Parameters

Name	Type	Description	Default
expr	ir.Column | str	The expression or column name to use for sorting	required

See Also

Value.desc()

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.examples.penguins.fetch()
>>> t[["species", "year"]].order_by(letsql.desc("year")).head()
┏━━━━━━━━━┳━━━━━━━┓
┃ species ┃ year  ┃
┡━━━━━━━━━╇━━━━━━━┩
│ string  │ int64 │
├─────────┼───────┤
│ Adelie  │  2009 │
│ Adelie  │  2009 │
│ Adelie  │  2009 │
│ Adelie  │  2009 │
│ Adelie  │  2009 │
└─────────┴───────┘

Returns

Name	Type	Description
	ir.ValueExpr	An expression

asc

asc(expr)

Create an ascending sort key from asc or column name.

Parameters

Name	Type	Description	Default
expr	ir.Column | str	The expression or column name to use for sorting	required

See Also

Value.asc()

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.examples.penguins.fetch()
>>> t[["species", "year"]].order_by(letsql.asc("year")).head()
┏━━━━━━━━━┳━━━━━━━┓
┃ species ┃ year  ┃
┡━━━━━━━━━╇━━━━━━━┩
│ string  │ int64 │
├─────────┼───────┤
│ Adelie  │  2007 │
│ Adelie  │  2007 │
│ Adelie  │  2007 │
│ Adelie  │  2007 │
│ Adelie  │  2007 │
└─────────┴───────┘

Returns

Name	Type	Description
	ir.ValueExpr	An expression

preceding

preceding(value)

following

following(value)

and_

and_(*predicates)

Combine multiple predicates using &.

Parameters

Name	Type	Description	Default
predicates	ir.BooleanValue	Boolean value expressions	()

Returns

Name	Type	Description
	BooleanValue	A new predicate that evaluates to True if all composing predicates are True. If no predicates were provided, returns True.

or_

or_(*predicates)

Combine multiple predicates using |.

Parameters

Name	Type	Description	Default
predicates	ir.BooleanValue	Boolean value expressions	()

Returns

Name	Type	Description
	BooleanValue	A new predicate that evaluates to True if any composing predicates are True. If no predicates were provided, returns False.

random

random()

Return a random floating point number in the range [0.0, 1.0).

Similar to in the Python standard library.

ibis.random() will generate a column of distinct random numbers even if the same instance of ibis.random() is reused.

When Ibis compiles an expression to SQL, each place where random is used will render as a separate call to the given backend’s random number generator.

import letsql r_a = letsql.random() # doctest: +SKIP

Returns

Name	Type	Description
	FloatingScalar	Random float value expression

uuid

uuid()

Return a random UUID version 4 value.

Similar to [(’uuid.uuid4`) in the Python standard library.

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> letsql.uuid()
UUID('e57e927b-aed2-483b-9140-dc32a26cad95')

Returns

Name	Type	Description
	UUIDScalar	Random UUID value expression

case

case()

Begin constructing a case expression.

Use the .when method on the resulting object followed by .end to create a complete case expression.

Returns

Name	Type	Description
	SearchedCaseBuilder	A builder object to use for constructing a case expression.

See Also

Value.case()

Examples

>>> import letsql
>>> from letsql.vendor.ibis import _
>>> letsql.options.interactive = True
>>> t = letsql.memtable(
...     {
...         "left": [1, 2, 3, 4],
...         "symbol": ["+", "-", "*", "/"],
...         "right": [5, 6, 7, 8],
...     }
... )
>>> t.mutate(
...     result=(
...         letsql.case()
...         .when(_.symbol == "+", _.left + _.right)
...         .when(_.symbol == "-", _.left - _.right)
...         .when(_.symbol == "*", _.left * _.right)
...         .when(_.symbol == "/", _.left / _.right)
...         .end()
...     )
... )
┏━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━┓
┃ left  ┃ symbol ┃ right ┃ result  ┃
┡━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━┩
│ int64 │ string │ int64 │ float64 │
├───────┼────────┼───────┼─────────┤
│     1 │ +      │     5 │     6.0 │
│     2 │ -      │     6 │    -4.0 │
│     3 │ *      │     7 │    21.0 │
│     4 │ /      │     8 │     0.5 │
└───────┴────────┴───────┴─────────┘

now

now()

Return an expression that will compute the current timestamp.

Returns

Name	Type	Description
	TimestampScalar	An expression representing the current timestamp.

today

today()

Return an expression that will compute the current date.

Returns

Name	Type	Description
	DateScalar	An expression representing the current date.

rank

rank()

Compute position of first element within each equal-value group in sorted order.

Equivalent to SQL’s RANK() window function.

Returns

Name	Type	Description
	Int64Column	The min rank

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(rank=letsql.rank().over(order_by=t.values))
┏━━━━━━━━┳━━━━━━━┓
┃ values ┃ rank  ┃
┡━━━━━━━━╇━━━━━━━┩
│ int64  │ int64 │
├────────┼───────┤
│      1 │     0 │
│      1 │     0 │
│      2 │     2 │
│      2 │     2 │
│      2 │     2 │
│      3 │     5 │
└────────┴───────┘

dense_rank

dense_rank()

Position of first element within each group of equal values.

Values are returned in sorted order and duplicate values are ignored.

Equivalent to SQL’s DENSE_RANK().

Returns

Name	Type	Description
	IntegerColumn	The rank

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(rank=letsql.dense_rank().over(order_by=t.values))
┏━━━━━━━━┳━━━━━━━┓
┃ values ┃ rank  ┃
┡━━━━━━━━╇━━━━━━━┩
│ int64  │ int64 │
├────────┼───────┤
│      1 │     0 │
│      1 │     0 │
│      2 │     1 │
│      2 │     1 │
│      2 │     1 │
│      3 │     2 │
└────────┴───────┘

percent_rank

percent_rank()

Return the relative rank of the values in the column.

Returns

Name	Type	Description
	FloatingColumn	The percent rank

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(pct_rank=letsql.percent_rank().over(order_by=t.values))
┏━━━━━━━━┳━━━━━━━━━━┓
┃ values ┃ pct_rank ┃
┡━━━━━━━━╇━━━━━━━━━━┩
│ int64  │ float64  │
├────────┼──────────┤
│      1 │      0.0 │
│      1 │      0.0 │
│      2 │      0.4 │
│      2 │      0.4 │
│      2 │      0.4 │
│      3 │      1.0 │
└────────┴──────────┘

cume_dist

cume_dist()

Return the cumulative distribution over a window.

Returns

Name	Type	Description
	FloatingColumn	The cumulative distribution

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(dist=letsql.cume_dist().over(order_by=t.values))
┏━━━━━━━━┳━━━━━━━━━━┓
┃ values ┃ dist     ┃
┡━━━━━━━━╇━━━━━━━━━━┩
│ int64  │ float64  │
├────────┼──────────┤
│      1 │ 0.333333 │
│      1 │ 0.333333 │
│      2 │ 0.833333 │
│      2 │ 0.833333 │
│      2 │ 0.833333 │
│      3 │ 1.000000 │
└────────┴──────────┘

ntile

ntile(buckets)

Return the integer number of a partitioning of the column values.

Parameters

Name	Type	Description	Default
buckets	int | ir.IntegerValue	Number of buckets to partition into	required

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(ntile=letsql.ntile(2).over(order_by=t.values))
┏━━━━━━━━┳━━━━━━━┓
┃ values ┃ ntile ┃
┡━━━━━━━━╇━━━━━━━┩
│ int64  │ int64 │
├────────┼───────┤
│      1 │     0 │
│      1 │     0 │
│      2 │     0 │
│      2 │     1 │
│      2 │     1 │
│      3 │     1 │
└────────┴───────┘

row_number

row_number()

Return an analytic function expression for the current row number.

row_number is normalized across backends to start at 0

Returns

Name	Type	Description
	IntegerColumn	A column expression enumerating rows

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"values": [1, 2, 1, 2, 3, 2]})
>>> t.mutate(rownum=letsql.row_number())
┏━━━━━━━━┳━━━━━━━━┓
┃ values ┃ rownum ┃
┡━━━━━━━━╇━━━━━━━━┩
│ int64  │ int64  │
├────────┼────────┤
│      1 │      0 │
│      2 │      1 │
│      1 │      2 │
│      2 │      3 │
│      3 │      4 │
│      2 │      5 │
└────────┴────────┘

read_csv

read_csv(sources, table_name=None, **kwargs)

Lazily load a CSV or set of CSVs.

This function delegates to the read_csv method on the current default backend (DuckDB or ibis.config.default_backend).

Parameters

Name	Type	Description	Default
sources	str | Path | Sequence[str | Path]	A filesystem path or URL or list of same. Supports CSV and TSV files.	required
table_name	str | None	A name to refer to the table. If not provided, a name will be generated.	None
kwargs	Any	Backend-specific keyword arguments for the file type. For the DuckDB backend used by default, please refer to: * CSV/TSV: https://duckdb.org/docs/data/csv/overview.html#parameters.	{}

Returns

Name	Type	Description
	ir.Table	Table expression representing a file

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> lines = '''a,b
... 1,d
... 2,
... ,f
... '''
>>> with open("/tmp/lines.csv", mode="w") as f:
...     nbytes = f.write(lines)  # nbytes is unused
>>> t = letsql.read_csv("/tmp/lines.csv")
>>> t
┏━━━━━━━┳━━━━━━━━┓
┃ a     ┃ b      ┃
┡━━━━━━━╇━━━━━━━━┩
│ int64 │ string │
├───────┼────────┤
│     1 │ d      │
│     2 │ NULL   │
│  NULL │ f      │
└───────┴────────┘

read_parquet

read_parquet(sources, table_name=None, **kwargs)

Lazily load a parquet file or set of parquet files.

This function delegates to the read_parquet method on the current default backend (DuckDB or ibis.config.default_backend).

Parameters

Name	Type	Description	Default
sources	str | Path | Sequence[str | Path]	A filesystem path or URL or list of same.	required
table_name	str | None	A name to refer to the table. If not provided, a name will be generated.	None
kwargs	Any	Backend-specific keyword arguments for the file type. For the DuckDB backend used by default, please refer to: * Parquet: https://duckdb.org/docs/data/parquet	{}

Returns

Name	Type	Description
	ir.Table	Table expression representing a file

Examples

>>> import letsql
>>> import pandas as pd
>>> letsql.options.interactive = True
>>> df = pd.DataFrame({"a": [1, 2, 3], "b": list("ghi")})
>>> df
   a  b
0  1  g
1  2  h
2  3  i
>>> df.to_parquet("/tmp/data.parquet")
>>> t = letsql.read_parquet("/tmp/data.parquet")
>>> t
┏━━━━━━━┳━━━━━━━━┓
┃ a     ┃ b      ┃
┡━━━━━━━╇━━━━━━━━┩
│ int64 │ string │
├───────┼────────┤
│     1 │ g      │
│     2 │ h      │
│     3 │ i      │
└───────┴────────┘

register

register(source, table_name=None, **kwargs)

read_postgres

read_postgres(uri, table_name=None, **kwargs)

read_sqlite

read_sqlite(path, *, table_name=None)

union

union(table, *rest, distinct=False)

Compute the set union of multiple table expressions.

The input tables must have identical schemas.

Parameters

Name	Type	Description	Default
table	ir.Table	A table expression	required
*rest	ir.Table	Additional table expressions	()
distinct	bool	Only return distinct rows	False

Returns

Name	Type	Description
	Table	A new table containing the union of all input tables.

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t1 = letsql.memtable({"a": [1, 2]})
>>> t1
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
│     2 │
└───────┘
>>> t2 = letsql.memtable({"a": [2, 3]})
>>> t2
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     2 │
│     3 │
└───────┘
>>> letsql.union(t1, t2)  # union all by default
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
│     2 │
│     2 │
│     3 │
└───────┘
>>> letsql.union(t1, t2, distinct=True).order_by("a")
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
│     2 │
│     3 │
└───────┘

intersect

intersect(table, *rest, distinct=True)

Compute the set intersection of multiple table expressions.

The input tables must have identical schemas.

Parameters

Name	Type	Description	Default
table	ir.Table	A table expression	required
*rest	ir.Table	Additional table expressions	()
distinct	bool	Only return distinct rows	True

Returns

Name	Type	Description
	Table	A new table containing the intersection of all input tables.

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t1 = letsql.memtable({"a": [1, 2]})
>>> t1
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
│     2 │
└───────┘
>>> t2 = letsql.memtable({"a": [2, 3]})
>>> t2
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     2 │
│     3 │
└───────┘
>>> letsql.intersect(t1, t2)
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     2 │
└───────┘

difference

difference(table, *rest, distinct=True)

Compute the set difference of multiple table expressions.

The input tables must have identical schemas.

Parameters

Name	Type	Description	Default
table	ir.Table	A table expression	required
*rest	ir.Table	Additional table expressions	()
distinct	bool	Only diff distinct rows not occurring in the calling table	True

Returns

Name	Type	Description
	Table	The rows present in self that are not present in tables.

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t1 = letsql.memtable({"a": [1, 2]})
>>> t1
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
│     2 │
└───────┘
>>> t2 = letsql.memtable({"a": [2, 3]})
>>> t2
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     2 │
│     3 │
└───────┘
>>> letsql.difference(t1, t2)
┏━━━━━━━┓
┃ a     ┃
┡━━━━━━━┩
│ int64 │
├───────┤
│     1 │
└───────┘

ifelse

ifelse(condition, true_expr, false_expr)

Construct a ternary conditional expression.

Parameters

Name	Type	Description	Default
condition	Any	A boolean expression	required
true_expr	Any	Expression to return if condition evaluates to True	required
false_expr	Any	Expression to return if condition evaluates to False or NULL	required

Returns

Name	Type	Description
Value	ir.Value	The value of true_expr if condition is True else false_expr

See Also

BooleanValue.ifelse()

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> t = letsql.memtable({"condition": [True, False, True, None]})
>>> letsql.ifelse(t.condition, "yes", "no")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ IfElse(condition, 'yes', 'no') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                         │
├────────────────────────────────┤
│ yes                            │
│ no                             │
│ yes                            │
│ no                             │
└────────────────────────────────┘

coalesce

coalesce(*args)

Return the first non-null value from args.

Parameters

Name	Type	Description	Default
args	Any	Arguments from which to choose the first non-null value	()

Returns

Name	Type	Description
	Value	Coalesced expression

See Also

Value.coalesce() Value.fill_null()

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> letsql.coalesce(None, 4, 5)
4

greatest

greatest(*args)

Compute the largest value among the supplied arguments.

Parameters

Name	Type	Description	Default
args	Any	Arguments to choose from	()

Returns

Name	Type	Description
	Value	Maximum of the passed arguments

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> letsql.greatest(None, 4, 5)
5

least

least(*args)

Compute the smallest value among the supplied arguments.

Parameters

Name	Type	Description	Default
args	Any	Arguments to choose from	()

Returns

Name	Type	Description
	Value	Minimum of the passed arguments

Examples

>>> import letsql
>>> letsql.options.interactive = True
>>> letsql.least(None, 4, 5)
4

range

range(start, stop, step)

Generate a range of values.

Integer ranges are supported, as well as timestamp ranges.

start is inclusive and stop is exclusive, just like Python’s builtin range.

When step equals 0, however, this function will return an empty array.

Python’s range will raise an exception when step is zero.

Parameters

Name	Type	Description	Default
start		Lower bound of the range, inclusive.	required
stop		Upper bound of the range, exclusive.	required
step		Step value. Optional, defaults to 1.	required

Returns

Name	Type	Description
	ArrayValue	An array of values

Examples

>>> import letsql
>>> letsql.options.interactive = True

Range using only a stop argument

>>> letsql.range(5)
[0, 1, ... +3]

Simple range using start and stop

>>> letsql.range(1, 5)
[1, 2, ... +2]

Generate an empty range

>>> letsql.range(0)
[]

Negative step values are supported

>>> letsql.range(10, 4, -2)
[10, 8, ... +1]

ibis.range behaves the same as Python’s range …

>>> letsql.range(0, 7, -1)
[]

… except when the step is zero, in which case ibis.range returns an empty array

>>> letsql.range(0, 5, 0)
[]

Because the resulting expression is array, you can unnest the values

>>> letsql.range(5).unnest().name("numbers")
┏━━━━━━━━━┓
┃ numbers ┃
┡━━━━━━━━━┩
│ int8    │
├─────────┤
│       0 │
│       1 │
│       2 │
│       3 │
│       4 │
└─────────┘

timestamp

timestamp(
    value_or_year,
    month=None,
    day=None,
    hour=None,
    minute=None,
    second=None,
    /,
    timezone=None,
)

Construct a timestamp scalar or column.

Parameters

Name	Type	Description	Default
value_or_year		Either a string value or datetime.datetime to coerce to a timestamp, or an integral value representing the timestamp year component.	required
month		The timestamp month component; required if value_or_year is a year.	None
day		The timestamp day component; required if value_or_year is a year.	None
hour		The timestamp hour component; required if value_or_year is a year.	None
minute		The timestamp minute component; required if value_or_year is a year.	None
second		The timestamp second component; required if value_or_year is a year.	None
timezone		The timezone name, or none for a timezone-naive timestamp.	None

Returns

Name	Type	Description
	TimestampValue	A timestamp expression

Examples

>>> import letsql
>>> letsql.options.interactive = True

Create a timestamp scalar from a string

>>> letsql.timestamp("2023-01-02T03:04:05")
Timestamp('2023-01-02 03:04:05')

Create a timestamp scalar from components

>>> letsql.timestamp(2023, 1, 2, 3, 4, 5)
Timestamp('2023-01-02 03:04:05')

Create a timestamp column from components

>>> t = letsql.memtable({"y": [2001, 2002], "m": [1, 4], "d": [2, 5], "h": [3, 6]})
>>> letsql.timestamp(t.y, t.m, t.d, t.h, 0, 0).name("timestamp")
┏━━━━━━━━━━━━━━━━━━━━━┓
┃ timestamp           ┃
┡━━━━━━━━━━━━━━━━━━━━━┩
│ timestamp           │
├─────────────────────┤
│ 2001-01-02 03:00:00 │
│ 2002-04-05 06:00:00 │
└─────────────────────┘

date

date(value_or_year, month=None, day=None, /)

time

time(value_or_hour, minute=None, second=None, /)

Return a time literal if value is coercible to a time.

Parameters

Name	Type	Description	Default
value_or_hour		Either a string value or datetime.time to coerce to a time, or an integral value representing the time hour component.	required
minute		The time minute component; required if value_or_hour is an hour.	None
second		The time second component; required if value_or_hour is an hour.	None

Returns

Name	Type	Description
	TimeValue	A time expression

Examples

>>> import letsql
>>> letsql.options.interactive = True

Create a time scalar from a string

>>> letsql.time("01:02:03")
datetime.time(1, 2, 3)

Create a time scalar from hour, minute, and second

>>> letsql.time(1, 2, 3)
datetime.time(1, 2, 3)

Create a time column from hour, minute, and second

>>> t = letsql.memtable({"h": [1, 4], "m": [2, 5], "s": [3, 6]})
>>> letsql.time(t.h, t.m, t.s).name("time")
┏━━━━━━━━━━┓
┃ time     ┃
┡━━━━━━━━━━┩
│ time     │
├──────────┤
│ 01:02:03 │
│ 04:05:06 │
└──────────┘

interval

interval(
    value=None,
    unit='s',
    *,
    years=None,
    quarters=None,
    months=None,
    weeks=None,
    days=None,
    hours=None,
    minutes=None,
    seconds=None,
    milliseconds=None,
    microseconds=None,
    nanoseconds=None,
)

Return an interval literal expression.

Parameters

Name	Type	Description	Default
value	int | datetime.timedelta | None	Interval value.	None
unit	str	Unit of value	's'
years	int | None	Number of years	None
quarters	int | None	Number of quarters	None
months	int | None	Number of months	None
weeks	int | None	Number of weeks	None
days	int | None	Number of days	None
hours	int | None	Number of hours	None
minutes	int | None	Number of minutes	None
seconds	int | None	Number of seconds	None
milliseconds	int | None	Number of milliseconds	None
microseconds	int | None	Number of microseconds	None
nanoseconds	int | None	Number of nanoseconds	None

Returns

Name	Type	Description
	IntervalScalar	An interval expression

to_sql

to_sql(expr, pretty=True)

Return the formatted SQL string for an expression.

Parameters

Name	Type	Description	Default
expr	ir.Expr	Ibis expression.	required
pretty	bool	Whether to use pretty formatting.	True

Returns

Name	Type	Description
	str	Formatted SQL string

execute

execute(expr, **kwargs)

to_pyarrow_batches

to_pyarrow_batches(expr, *, chunk_size=1000000, **kwargs)

to_pyarrow

to_pyarrow(expr, **kwargs)

to_parquet

to_parquet(expr, path, params=None, **kwargs)

get_plans

get_plans(expr)