Implementation:Lance format Lance LogicalExpr

Knowledge Sources	Lance
Domains	DataFusion_Integration, Query_Execution
Last Updated	2026-02-08 19:33 GMT

Overview

The LogicalExpr module extends DataFusion logical expressions with type resolution, coercion, and utility functions for Lance's schema-aware query processing.

Description

This module provides functions and traits for resolving and coercing DataFusion logical expressions against a Lance schema. Key components include:

• resolve_expr -- Recursively resolves a logical Expr by coercing literal values to match their corresponding column types in the Lance schema. Handles BinaryExpr (including compound right-hand expressions), Between, InList, IsNotNull, IsNull, Not, and boolean AND/OR connectives.
• resolve_column_type -- Given an expression that references a column (possibly through nested struct field access via GetFieldFunc), resolves the data type by walking the Lance schema hierarchy.
• get_as_string_scalar_opt -- A helper that extracts a string value from a Expr::Literal(ScalarValue::Utf8(...)), returning None for non-string expressions.
• coerce_expr -- Coerces an expression (typically a literal or nested binary expression) to a target data type using safe_coerce_scalar.
• coerce_filter_type_to_boolean -- Wraps non-boolean filter expressions (e.g., is_valid columns of type Utf8) with an IS NOT NULL check to ensure the expression evaluates to a boolean.
• ExprExt trait -- Extends Expr with a columns_and_types method that extracts all column references and their resolved types from an expression tree.
• field_path_to_expr -- Converts a dot-separated field path string (e.g., "metadata.location.x") into a nested Expr::ScalarFunction(GetFieldFunc(...)) expression.

Usage

Use this module when you need to:

• Resolve filter expressions parsed from SQL against a Lance schema before execution
• Coerce literal types to match column types for correct comparison semantics
• Extract column references and their types from complex expression trees
• Convert field path strings into DataFusion expressions for nested struct access

Code Reference

Source Location

rust/lance-datafusion/src/logical_expr.rs

Signature

pub fn resolve_expr(expr: &Expr, schema: &Schema) -> Result<Expr>
pub fn resolve_column_type(expr: &Expr, schema: &Schema) -> Option<DataType>
pub fn get_as_string_scalar_opt(expr: &Expr) -> Option<&str>
pub fn coerce_expr(expr: &Expr, dtype: &DataType) -> Result<Expr>
pub fn coerce_filter_type_to_boolean(expr: Expr) -> Expr
pub fn field_path_to_expr(field_path: &str) -> Result<Expr>

pub trait ExprExt {
    fn columns_and_types(&self, schema: &Schema) -> Vec<(String, Option<DataType>)>;
}

Import

use lance_datafusion::logical_expr::{
    resolve_expr, resolve_column_type, coerce_filter_type_to_boolean, field_path_to_expr,
};

I/O Contract

Input	Type	Description
expr	&Expr	A DataFusion logical expression to resolve or coerce
schema	&Schema	The Lance schema providing column type information

Output	Type	Description
resolve_expr	Result<Expr>	The expression with all literals coerced to match their column types
resolve_column_type	Option<DataType>	The resolved Arrow DataType of the referenced column, or None
field_path_to_expr	Result<Expr>	A nested GetField expression for the given dot-separated path

Usage Examples

use lance_datafusion::logical_expr::{resolve_expr, field_path_to_expr};
use lance_core::datatypes::Schema;

// Resolve filter expression against schema
let resolved = resolve_expr(&filter_expr, &lance_schema)?;

// Convert a field path to an expression
let expr = field_path_to_expr("metadata.location.x")?;
// Produces: get_field(get_field(Column("metadata"), "location"), "x")

Related Pages

• Implementation:Lance_format_Lance_SafeScalarValue -- Safe scalar coercion used by resolve_expr
• Implementation:Lance_format_Lance_FilterPlanner -- Planner that calls resolve_expr on parsed SQL filters
• Implementation:Lance_format_Lance_ProjectionPlan -- Projection planning that uses column type resolution