Struct ScanOptions 

pub struct ScanOptions {

    pub limit: Option<usize>,
    pub offset: usize,
    pub batch_size: usize,
    pub vertex_id_range: Option<Range<i64>>,
    pub edge_src_id_range: Option<Range<i64>>,
    pub edge_type: Option<String>,
    pub tag: Option<String>,
    pub projection: Option<Vec<RequiredProperty>>,
    pub topology_only: bool,
    pub read_timestamp: Option<u64>,
    pub predicate: Option<Vec<ScanPredicate>>,
    pub column_block_mode: bool,
    pub internal_id_allowlist: Option<Vec<u32>>,
    pub edge_table_allowlist: Option<Vec<EdgeTableKey>>,
    pub shard_slice: Option<ShardSlice>,
    pub edge_src_slice: Option<ShardSlice>,
}

Unified scan options that configure cursor behavior.

This is the contract between the query planner/executor and the storage layer. Future phases will add predicate pushdown, projection, partition, range, and snapshot support.

Fields

limit: Option<usize>

Maximum number of rows to return (None = unlimited).

offset: usize

Number of matching rows to skip before emitting the first row.

batch_size: usize

Batch size for cursor reads.

vertex_id_range: Option<Range<i64>>

Optional vertex ID range filter over the external vertex ID (the same i64 domain as PartitionSpec ranges). Only vertices whose external ID falls in this range (inclusive of start, exclusive of end) are returned. When set, this filter is applied at scan time, not as a post-filter.

edge_src_id_range: Option<Range<i64>>

Optional edge source ID range filter. Only edges whose source ID (parsed as i64) falls in this range are returned.

edge_type: Option<String>

Edge type filter (for edge scans only).

tag: Option<String>

Optional tag filter for vertex scans: only rows whose tag matches this name are scanned. The tag tables of all other tags are skipped at scan time (the query layer may therefore elide the matching contains(labels(v), ...) residual conjunct).

projection: Option<Vec<RequiredProperty>>

Optional property projection pushed into the physical scan.

topology_only: bool

Topology-only vertex scan: return vertex identities and tags with zero property decode. Only valid with an empty projection and no pushed predicates; the cursor rejects any other combination at open so misuse surfaces as an error instead of silently wrong rows.

read_timestamp: Option<u64>

Read timestamp captured by the caller.

predicate: Option<Vec<ScanPredicate>>

Optional conjunctive scan predicates pushed from the query layer.

All predicates must match for a row to be emitted. The query layer keeps the original filter on top, so the pushdown is a pure pre-filter (see ScanPredicate).

column_block_mode: bool

Column-block scan mode: pull column-major batches from the storage cursor via VertexCursor::next_column_batch instead of row-major batches. Default off — the row-based path stays the fallback.

internal_id_allowlist: Option<Vec<u32>>

Optional internal-ID allowlist (semi-mask) for vertex scans: when set, the cursor decodes exactly these global internal IDs instead of enumerating the table’s live IDs. IDs that are deleted, invisible at the read timestamp, or out of range yield no row, mirroring the batch point-lookup semantics. Internal ID spaces are per tag table, so an allowlist requires ScanOptions::tag; opening without a tag fails. The join/expand layer uses this to push a known vertex set into the scan instead of scanning whole tables.

edge_table_allowlist: Option<Vec<EdgeTableKey>>

Optional edge-table allowlist for table-sharded parallel scans: when set, the edge cursor only drains tables whose key is listed. Shards partition the key set, so the union of shards covers every table of the edge type exactly once. None (default) scans all tables.

shard_slice: Option<ShardSlice>

Optional shard slice for parallel vertex scans: when set, the cursor enumerates only this slice of every tag table’s shard-local id space. Slices partition the enumeration space (not the external-id value space, which is hash-distributed over shards and cannot prune enumeration), so the union of all slices covers the table exactly once. None (default) enumerates the whole table.

edge_src_slice: Option<ShardSlice>

Optional shard slice for parallel edge scans: when set, the cursor walks only the edges whose source internal id falls in this slice of the source tables’ shard-local id space. Same division contract as shard_slice, applied to the edge source space so the union of all slices covers every edge exactly once. Composes with edge_src_id_range, which stays a row-level external-id filter. None (default) walks the whole source space.

Implementations

impl ScanOptions

pub const DEFAULT_BATCH_SIZE: usize = 1024

pub fn new() -> ScanOptions

pub fn with_edge_type(self, edge_type: String) -> ScanOptions

Builder: set edge type filter.

pub fn with_limit(self, limit: usize) -> ScanOptions

Builder: set row limit.

pub fn with_offset(self, offset: usize) -> ScanOptions

Builder: set the number of matching rows to skip.

pub fn with_projection_named(self, projection: Vec<String>) -> ScanOptions

pub fn with_projection(self, projection: Vec<RequiredProperty>) -> ScanOptions

pub fn with_tag(self, tag: String) -> ScanOptions

Builder: restrict a vertex scan to a single tag by name.

pub fn with_internal_id_allowlist(self, ids: Vec<u32>) -> ScanOptions

Builder: decode exactly these global internal IDs instead of enumerating live IDs (semi-mask pushdown). Requires with_tag.

pub fn with_shard_slice(self, slice: ShardSlice) -> ScanOptions

Builder: enumerate only one shard slice of the table instead of the whole table (parallel-scan division).

pub fn with_edge_src_slice(self, slice: ShardSlice) -> ScanOptions

Builder: walk only one shard slice of the edge source space instead of the whole space (parallel edge-scan division).

pub fn batch_size(&self) -> usize

Trait Implementations

impl Clone for ScanOptions

fn clone(&self) -> ScanOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ScanOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ScanOptions

fn default() -> ScanOptions

Returns the “default value” for a type.