Overview
Description
SqlQuery is a fluent builder-style class for executing SQL queries against a Lance dataset. It delegates query execution to the native Rust engine via JNI and returns results as an Apache Arrow ArrowReader for streaming batch processing. The query is executed against the dataset registered under a configurable table name (defaulting to "dataset"), with optional support for including row IDs and row addresses in the output.
Usage
A SqlQuery is constructed with a reference to a Dataset and a SQL string. The builder methods tableName(), withRowId(), and withRowAddr() allow further customization before calling intoBatchRecords() to execute the query and obtain a streaming ArrowReader. The native execution uses the Arrow C Data Interface for zero-copy data transfer.
Code Reference
Source Location
java/src/main/java/org/lance/SqlQuery.java
Signature
public class SqlQuery {
public SqlQuery(Dataset dataset, String sql);
public SqlQuery tableName(String tableName);
public SqlQuery withRowId(boolean withRowId);
public SqlQuery withRowAddr(boolean withAddr);
public ArrowReader intoBatchRecords() throws IOException;
public String toString();
}
Import
import org.lance.SqlQuery;
I/O Contract
Constructor Parameters
| Name |
Type |
Description
|
| dataset |
Dataset |
The Lance dataset to query against
|
| sql |
String |
The SQL query string to execute
|
Builder Methods
| Method |
Parameter Type |
Default |
Description
|
| tableName() |
String |
"dataset" |
Sets the table name used to reference the dataset in SQL
|
| withRowId() |
boolean |
false |
Whether to include row IDs in query results
|
| withRowAddr() |
boolean |
false |
Whether to include row addresses in query results
|
Return Values
| Method |
Return Type |
Description
|
| intoBatchRecords() |
ArrowReader |
Returns a streaming ArrowReader containing the query result batches
|
Exceptions
| Method |
Exception |
Condition
|
| intoBatchRecords() |
IOException |
Native query execution fails or stream allocation fails
|
Usage Examples
import org.lance.SqlQuery;
import org.lance.Dataset;
import org.apache.arrow.vector.ipc.ArrowReader;
// Simple query using default table name
Dataset dataset = Dataset.open().uri("/data/my_dataset.lance").build();
ArrowReader reader = new SqlQuery(dataset, "SELECT * FROM dataset WHERE id > 100")
.intoBatchRecords();
// Query with custom table name and row IDs
ArrowReader reader = new SqlQuery(dataset, "SELECT name, embedding FROM my_table LIMIT 50")
.tableName("my_table")
.withRowId(true)
.intoBatchRecords();
// Process results
while (reader.loadNextBatch()) {
VectorSchemaRoot batch = reader.getVectorSchemaRoot();
// Process each batch...
}
reader.close();
// Query with row addresses for advanced use cases
ArrowReader reader = new SqlQuery(dataset, "SELECT * FROM dataset")
.withRowId(true)
.withRowAddr(true)
.intoBatchRecords();
Related Pages
Page Connections
Double-click a node to navigate. Hold to expand connections.
