lancedb/docs/web/sql/scalar-functions.mdx

---
title: "Scalar functions"
sidebarTitle: "Scalar Functions"
description: "The per-row function set: math, string, regex, date/time, array, struct, and what Lance adds."
icon: calculator
keywords: ["scalar functions", "string functions", "math functions", "regex", "array functions", "json"]
availability:
  embedded: unavailable
  enterprise: available
---

Functions that take a value and return a value, one row at a time. The set is
based on DataFusion's registration plus Lance and deployment-specific
functions. The names below are selected examples, not an exhaustive catalog
for every deployment. Availability depends on the deployed version and build.

For per-group functions see [Aggregation](/sql/dql/aggregation); for per-window,
[Window functions](/sql/dql/window).

## Math {#math}

```text
abs  ceil  floor  round  trunc  signum  power  sqrt  cbrt  exp
ln  log  log2  log10  factorial  gcd  lcm  pi  random  nanvl
isnan  iszero  cot  degrees  radians  to_degrees  to_radians
sin  cos  tan  asin  acos  atan  atan2
sinh  cosh  tanh  asinh  acosh  atanh
```

## String {#string}

```text
ascii  bit_length  btrim  chr  concat  concat_ws  contains  ends_with
starts_with  levenshtein  lower  upper  ltrim  rtrim  octet_length
repeat  replace  split_part  to_hex  uuid
```

Unicode-aware variants:

```text
character_length  find_in_set  initcap  left  right  lpad  rpad
reverse  strpos  substr  substr_index  substring  translate
```

<Note>
For keyword matching on a text column, [`contains_tokens`](#contains-tokens) is
index-accelerated where `contains` and `LIKE` are not.
</Note>

## Regular expressions {#regex}

```text
regexp_count  regexp_instr  regexp_like  regexp_match  regexp_replace
```

## Date and time {#datetime}

```text
current_date  current_time  date_bin  date_part  date_trunc
from_unixtime  to_unixtime  make_date  make_time  to_char
to_date  to_time  to_local_time
```

`date_bin` is the one worth knowing for analytics: it buckets timestamps into
fixed-width intervals, which is how you build a time series without a
self-join.

```sql
SELECT date_bin(INTERVAL '1 hour', created_at) AS hour, count(*)
FROM events GROUP BY hour ORDER BY hour
```

## Arrays and maps {#arrays}

```text
make_array  array_has  array_filter  array_transform  array_any_match
array_compact  array_normalize  array_slice  arrays_zip  cardinality
flatten  range  generate_series
```

```text
map  map_keys  map_values  map_entries  map_extract
```

Distance functions over arrays:

```text
cosine_distance  distance  exact_distance  inner_product
```

<Warning>
Distance functions can evaluate arrays per row. Some deployment versions also
recognize `ORDER BY distance(vector, query_vector) LIMIT k` over a table scan
and plan it as vector search, with indexed or flat search as appropriate.
Where available, `exact_distance` evaluates distance without that rewrite.
Confirm the
functions supported by your deployment and inspect SQL
[`EXPLAIN`](/sql/dql/explain); the function name alone does not guarantee an
index-backed plan. See [SQL vector search](/basics/sql#no-vector-sql).
</Warning>

A third, optional argument is a comma-separated options string. `metric`
selects `l2` (default, alias `euclidean`), `cosine`, or `dot`; the
index-search rewrite also reads `nprobes` and `use_index`:

```sql
SELECT id FROM documents
ORDER BY distance(embedding, ARRAY[0.1, 0.2, 0.3], 'metric=cosine,nprobes=20')
LIMIT 10

-- Force a flat scan, bypassing the index:
SELECT id FROM documents
ORDER BY exact_distance(embedding, ARRAY[0.1, 0.2, 0.3], 'use_index=false')
LIMIT 10
```

## Structs and fields {#structs}

```text
named_struct  get_field  coalesce  nullif  nvl  nvl2  greatest  least
union_extract  union_tag
```

## Crypto and encoding {#crypto}

```text
digest  md5  sha224  sha256  sha384  sha512  encode  decode
```

## Type functions {#type}

```text
arrow_cast  arrow_try_cast  arrow_typeof  arrow_field  arrow_metadata
with_metadata  version
```

Use `arrow_typeof` to inspect the Arrow data type of a column or expression:

```sql
SELECT arrow_typeof(vector) FROM documents LIMIT 1
-- FixedSizeList(Field { name: "item", data_type: Float32, .. }, 1536)
```

`arrow_cast` casts to an Arrow type by name, reaching types SQL has no spelling
for. See [Data types](/sql/data-types).

## What Lance adds {#lance}

These are registered by Lance on top of DataFusion's set.

### `contains_tokens(column, tokens)` {#contains-tokens}

```sql
SELECT * FROM my_docs WHERE contains_tokens(text, 'fox jumps dog')
```

True when the column contains **all** the tokens, split on whitespace and
punctuation. Equivalent to an `fts()` match query with fuzziness off, `AND`
semantics and the simple tokenizer.

**Index-accelerated.** When the column has a full-text index that suits the
query, the planner uses it instead of scanning, which is the reason to prefer
it over `LIKE` for keyword tests.

### `ivf_partition(vector, ...)` {#ivf-partition}

```sql
SELECT ivf_partition(embedding, selection => 'random', count => 100, seed => 42) AS partition,
       array_agg(id) AS ids
FROM documents
GROUP BY partition
```

Assigns each row to one of `count` IVF-style partitions over `vector`, using
the named arguments `selection` (partition-center strategy; `'random'` is
sampled with `seed`) and `seed`. Grouping by its result buckets rows by
vector proximity without building or querying a vector index — useful for
blocking a large table into comparable chunks, such as before a pairwise
similarity pass.

### `blob_descriptor(column)` {#blob-descriptor}

```sql
SELECT id, blob_descriptor(video) AS descriptor FROM videos
```

A [BlobV2](/management/table#managed-blobs) column's bytes are not fetched by
a plain `SELECT`: that already returns `large_binary`, the same as any other
binary column. `blob_descriptor` instead returns a small struct describing
where the payload lives, without reading it. Pass one row's descriptor to
the SDK's blob file reader to open that payload directly:

```python
rows = db.execute_query("SELECT id, blob_descriptor(video) AS descriptor FROM videos").read_all().to_pylist()
with table.open_blob_file(rows[0]["descriptor"]) as reader:
    payload = reader.read()
```

A descriptor is pinned to the table version it was read at: it keeps
resolving correctly even after the table is appended to and checked out to a
newer version.

### JSON accessors {#json}

| Function | Returns |
| --- | --- |
| `json_get(col, key)` | the value at `key`, still JSON |
| `json_get_string(col, key)` | `Utf8` |
| `json_get_int(col, key)` | `Int64` |
| `json_get_float(col, key)` | `Float64` |
| `json_get_bool(col, key)` | `Boolean` |
| `json_extract(col, path)` | `Utf8`: the value as JSON text, by path |
| `json_extract_with_type(col, path)` | a struct of the value as JSON and a type tag, by path |
| `json_exists(col, path)` | `Boolean` |
| `json_array_contains(col, value)` | `Boolean` |
| `json_array_length(col)` | length |

`json_get` returns JSON, so a typed accessor can read a field inside it:

```sql
SELECT * FROM events
WHERE json_get_string(json_get(data, 'user'), 'name') = 'Alice'
```

That works one level down. A `json_get` nested inside another `json_get` is
refused, so reach a deeper value with `json_extract` and a JSONPath instead. It
returns JSON text, so a string compares with its quotes:

```sql
SELECT * FROM events
WHERE json_extract(data, '$.user.profile.name') = '"Alice"'
```

**`json_get`, its typed variants, and `json_extract` are index-accelerated** by a
JSON scalar index on the column. The rest evaluate per row.

### Geospatial {#geo}

<Warning>
Lance defines `st_*` functions on GeoArrow, but they sit behind a build feature
**LanceDB does not ship**. Calling one returns an error naming the missing
feature rather than an unknown-function error, and the spatial index is gated
the same way.
</Warning>

## Additional scalar functions {#escape-hatch}

SQL queries can call functions registered with the server, including functions
not listed on this page. Consult
[DataFusion's scalar function reference](https://datafusion.apache.org/user-guide/sql/scalar_functions.html)
for version 54. Functions documented for a newer DataFusion release may not be
available in your LanceDB Enterprise version.