Implementation:Lance format Lance LqCli

Knowledge Sources	Lance
Domains	CLI, Tooling
Last Updated	2026-02-08 19:33 GMT

Overview

Description

The lq binary is a command-line tool for inspecting and operating on Lance datasets. Built with clap for argument parsing and tokio for async runtime, it provides three subcommands:

• Inspect -- Displays dataset metadata including URI, latest version, total versions, total record count, and schema
• Query -- Scans and pretty-prints records from a dataset (default limit: 100 rows)
• Index -- Creates vector indices on dataset columns (currently supports IVF-PQ index type)

The Index subcommand supports configurable parameters for IVF-PQ indices including number of partitions, number of sub-vectors, and distance metric type (L2 or cosine).

Usage

The lq binary is compiled from rust/lance/src/bin/lq.rs and serves as a developer tool for quick dataset inspection and index creation from the command line.

Code Reference

Source Location

rust/lance/src/bin/lq.rs

Signature

#[derive(Parser)]
#[command(author, version, about, long_about = None)]
struct Args {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    Inspect { uri: String },
    Query { uri: String, #[arg(short, default_value_t = 100)] n: i64 },
    Index {
        #[arg(value_enum)] action: IndexAction,
        uri: String,
        #[arg(short, long)] column: Option<String>,
        #[arg(short, long)] name: Option<String>,
        #[arg(short = 't', long = "type", value_enum)] index_type: Option<IndexType>,
        #[arg(short = 'p', long, default_value_t = 64)] num_partitions: usize,
        #[arg(short = 's', long, default_value_t = 8)] num_sub_vectors: usize,
        #[arg(short = 'm', long)] metric_type: Option<String>,
    },
}

#[tokio::main]
async fn main() -> Result<()>;

Import

This is a binary target and is not imported as a library. It is invoked directly:

cargo run --bin lq -- <subcommand> [options]

I/O Contract

Inputs

Parameter	Type	Description
uri	String	Path or URI to the Lance dataset (local path, S3, GCS, etc.)
n	i64	Number of records to display in Query mode (default: 100)
column	Option<String>	Column name to build index on (required for Index command)
index_type	Option<IndexType>	Index type; currently only ivf-pq is supported
num_partitions	usize	Number of IVF partitions (default: 64)
num_sub_vectors	usize	Number of Product Quantizer sub-vectors (default: 8)
metric_type	Option<String>	Distance metric: "l2" or "cosine" (default: "l2")

Outputs

Output	Description
stdout	Dataset metadata (Inspect), pretty-printed record batches (Query), or index creation confirmation (Index)
exit code	0 on success, non-zero on error

Usage Examples

# Inspect a dataset
lq inspect /path/to/dataset.lance

# Query first 50 rows
lq query /path/to/dataset.lance -n 50

# Create an IVF-PQ index
lq index create /path/to/dataset.lance \
    -c vector_column \
    -t ivf-pq \
    -p 128 \
    -s 16 \
    -m cosine

Related Pages

• Lance_format_Lance_CrateRoot -- Main Lance crate that provides Dataset used by lq
• Lance_format_Lance_LanceTableProvider -- DataFusion integration for more advanced querying