Skip to content

Create a nanoarrow_array_stream from a Polars object

Description

Create a nanoarrow_array_stream from a Polars object

Usage

## S3 method for class 'polars_data_frame'
as_nanoarrow_array_stream(
  x,
  ...,
  schema = NULL,
  polars_compat_level = c("newest", "oldest")
)

# S3 method for class 'polars_series'
as_nanoarrow_array_stream(
  x,
  ...,
  schema = NULL,
  polars_compat_level = c("newest", "oldest")
)

Arguments

x A polars object
… Ignored.
schema [Experimental] An optional nanoarrow schema object. If specified, interpret the nanoarrow schema as a corresponding polars dtype and then convert the original object using \$cast(). Note that the schema of the returned object cannot be fully controlled because Polars does not support all Arrow types.
polars_compat_level [Experimental] Determines the compatibility level when exporting Polars’ internal data structures. When specifying a new compatibility level, Polars exports its internal data structures that might not be interpretable by other Arrow implementations. The level can be specified as the name (e.g., “newest”) or as a scalar integer (Currently, 0 or 1 is supported).
  • “newest” (default): Use the highest level, currently same as 1 (Low compatibility).
  • “oldest”: Same as 0 (High compatibility).

Value

A nanoarrow array stream

See Also

  • as_polars_series(\): Import an array stream as a Series via the Arrow C stream interface.

Examples

library("polars")


# Zero-copy round trip via nanoarrow
as_polars_series(letters[1:3], name = "letters") |>
  nanoarrow::as_nanoarrow_array_stream() |>
  as_polars_series()

#> shape: (3,)
#> Series: 'letters' [str]
#> [
#>  "a"
#>  "b"
#>  "c"
#> ]

# Specify the schema
as_polars_series(1:3, name = "numbers") |>
  nanoarrow::as_nanoarrow_array_stream(schema = nanoarrow::na_uint8()) |>
  as_polars_series()

#> shape: (3,)
#> Series: 'numbers' [u8]
#> [
#>  1
#>  2
#>  3
#> ]

# DataFrame support
pl$DataFrame(a = 1:3, b = letters[1:3]) |>
  nanoarrow::as_nanoarrow_array_stream() |>
  as_polars_df()

#> shape: (3, 2)
#> ┌─────┬─────┐
#> │ a   ┆ b   │
#> │ --- ┆ --- │
#> │ i32 ┆ str │
#> ╞═════╪═════╡
#> │ 1   ┆ a   │
#> │ 2   ┆ b   │
#> │ 3   ┆ c   │
#> └─────┴─────┘

# Compatibility level
as_polars_series(letters[1:3]) |>
  nanoarrow::as_nanoarrow_array_stream(polars_compat_level = 1) |>
  nanoarrow::infer_nanoarrow_schema() |>
  format()

#> [1] "<nanoarrow_schema string_view>"

as_polars_series(letters[1:3]) |>
  nanoarrow::as_nanoarrow_array_stream(polars_compat_level = "oldest") |>
  nanoarrow::infer_nanoarrow_schema() |>
  format()

#> [1] "<nanoarrow_schema large_string>"