> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RecordRetriever

> RecordRetriever — Kinetica Rust API

[gpudb\_api](https://docs.kinetica.com/content/api/rust/index.md)::<wbr />[record\_retriever](https://docs.kinetica.com/content/api/rust/record_retriever/index.md)
[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L220-L268)&#x20;

<pre>`pub struct RecordRetriever<R = GenericRecord> { /* private fields */ }`</pre>

Object that permits efficient retrieval of records from GPUdb, with support for multi-head access.`RecordRetriever` instances are thread safe and may be used from any number of tasks simultaneously. Records are returned as `R`: [`GenericRecord`](https://docs.kinetica.com/content/api/rust/generic_record/struct.GenericRecord)s by default, or any type serde can deserialize (see [`RetrievedRecord`](https://docs.kinetica.com/content/api/rust/record_retriever/trait.RetrievedRecord)).

## Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L270-L332)
impl [RecordRetriever](https://docs.kinetica.com/content/api/rust/record_retriever/struct.RecordRetriever.md)\<[GenericRecord](https://docs.kinetica.com/content/api/rust/generic_record/struct.GenericRecord.md)>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L294-L296)
pub async fn [new](#method.new)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), record\_type: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Type](https://docs.kinetica.com/content/api/rust/generic_record/struct.Type.md)>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<Self, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a retriever of the records of `table_name`, which are of `record_type`, returning them as [`GenericRecord`](https://docs.kinetica.com/content/api/rust/generic_record/struct.GenericRecord)s.The worker list is derived from the connection’s own worker addresses, and records are retrieved with no options.

##### Example

```rust theme={null}
use gpudb_api::{Kinetica, KineticaOptions, RecordRetriever, Type};
use std::sync::Arc;

let options = KineticaOptions::new();
let kinetica = Arc::new(
    Kinetica::new(vec!["http://localhost:9191".to_string()], options).await?
);
let record_type = Arc::new(Type::from_table(&kinetica, "my_table").await?);

let retriever = RecordRetriever::new(kinetica, "my_table", record_type).await?;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L299-L306)
pub async fn [with\_retriever\_options](#method.with_retriever_options)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), record\_type: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Type](https://docs.kinetica.com/content/api/rust/generic_record/struct.Type.md)>, options: [RecordRetrieverOptions](https://docs.kinetica.com/content/api/rust/record_retriever/struct.RecordRetrieverOptions.md), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<Self, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a retriever passing `options` to its retrievals.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L313-L320)
pub async fn [with\_workers](#method.with_workers)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), record\_type: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Type](https://docs.kinetica.com/content/api/rust/generic_record/struct.Type.md)>, workers: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<Self, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a retriever with the given worker list.`None` derives the list from the connection’s own worker addresses, which is the default; an empty list ([`WorkerList::empty`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.empty)) declines multi-head for this retriever.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L323-L331)
pub async fn [with\_options](#method.with_options)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), record\_type: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Type](https://docs.kinetica.com/content/api/rust/generic_record/struct.Type.md)>, workers: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)>, options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<Self, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a retriever with the given worker list and options.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L334-L366)
impl\<T: [DeserializeOwned](https://docs.rs/serde_core/1.0.228/serde_core/de/trait.DeserializeOwned.html) + [Send](https://doc.rust-lang.org/1.98.1/core/marker/trait.Send.html) + 'static> [RecordRetriever](https://docs.kinetica.com/content/api/rust/record_retriever/struct.RecordRetriever.md)\<T>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L357-L365)
pub async fn [new\_typed](#method.new_typed)( kinetica: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>, table\_name: &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html), record\_type: [Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Type](https://docs.kinetica.com/content/api/rust/generic_record/struct.Type.md)>, workers: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)>, options: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<Self, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Creates a retriever returning records decoded as `T`, from the Avro schema of `record_type`. `workers` and `options` are as for [`RecordRetriever::with_options`](https://docs.kinetica.com/content/api/rust/record_retriever/struct.RecordRetriever#method.with_options).

```rust theme={null}
use gpudb_api::{Kinetica, KineticaOptions, RecordRetriever, ShardKeyValue, Type};
use std::sync::Arc;

#[derive(serde::Deserialize)]
struct Row {
    id: i32,
    name: Option<String>,
}

let record_type = Arc::new(Type::from_table(&kinetica, "my_table").await?);
let retriever = RecordRetriever::<Row>::new_typed(kinetica, "my_table", record_type, None, None).await?;
let rows: Vec<Row> = retriever.get_by_key(&[ShardKeyValue::Int(1)], None).await?.data;
```

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L368-L1294)
impl\<R: [RetrievedRecord](https://docs.kinetica.com/content/api/rust/record_retriever/trait.RetrievedRecord.md)> [RecordRetriever](https://docs.kinetica.com/content/api/rust/record_retriever/struct.RecordRetriever.md)\<R>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L485-L487)
pub fn [kinetica](#method.kinetica)(\&self) -> &[Arc](https://doc.rust-lang.org/1.98.1/alloc/sync/struct.Arc.html)\<[Kinetica](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica.md)>

Gets the connection from which records will be retrieved.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L490-L492)
pub fn [table\_name](#method.table_name)(\&self) -> &[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)

Gets the name of the table from which records will be retrieved.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L496-L498)
pub fn [is\_using\_head\_rank](#method.is_using_head_rank)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether this RecordRetriever is using the head rank for simple record fetching (not utilizing the server’s key lookup feature).

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L501-L503)
pub fn [is\_doing\_worker\_lookup](#method.is_doing_worker_lookup)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns whether this RecordRetriever is using worker ranks for key lookups.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L506-L508)
pub fn [options](#method.options)(\&self) -> [HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>

Gets the options currently used for the retriever methods.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L511-L513)
pub fn [set\_options](#method.set_options)(\&self, options: [HashMap](https://doc.rust-lang.org/1.98.1/std/collections/hash/map/struct.HashMap.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html), [String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>)

Sets the options to be used for the retriever methods.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L899-L905)
pub async fn [get\_by\_key](#method.get_by_key)( \&self, key\_values: &\[[ShardKeyValue](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/enum.ShardKeyValue.md)\<'\_>], expression: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[GetRecordsResponse](https://docs.kinetica.com/content/api/rust/generated/api/struct.GetRecordsResponse.md)\<R>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Retrieves records with the given key values and filter expression.This method operates in four modes, depending on the parameters passed:

<ul>
  <li>**key values only**: attempts a direct-to-rank lookup for records matching the given key values</li>
  <li>**key values and expression**: attempts a direct-to-rank lookup for records matching the given key values, filtering them by the given expression</li>
  <li>**expression only**: requests, via the head rank, all records in the table matching the given filter expression</li>
  <li>**neither**: retrieves all records from the table via the head rank</li>
</ul>

##### Arguments

<ul>
  <li>`key_values` - The key values to use for the lookup, one per key column in key order, or none; these must correspond to either the explicit or implicit shard key for sharded tables or the primary key of replicated tables. Each must be of a type its column takes (see [`RecordKeyBuilder::build_expression`](https://docs.kinetica.com/content/api/rust/record_key_builder/struct.RecordKeyBuilder#method.build_expression)).</li>
  <li>`expression` - A filter expression that will be applied to the data requested by the key values; if no key values are specified this filter will be applied to all of the data in the target table</li>
</ul>

##### Returns

The requested records, decoded.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L918-L1013)
pub async fn [get\_by\_key\_with\_offset](#method.get_by_key_with_offset)( \&self, key\_values: &\[[ShardKeyValue](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/enum.ShardKeyValue.md)\<'\_>], expression: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)>, offset: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[GetRecordsResponse](https://docs.kinetica.com/content/api/rust/generated/api/struct.GetRecordsResponse.md)\<R>, [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Retrieves records with the given key values and filter expression, starting from an offset.

##### Arguments

<ul>
  <li>`key_values` - The key values to use for the lookup, or none</li>
  <li>`expression` - A filter expression</li>
  <li>`offset` - Offset of the record(s) within the result set to return</li>
</ul>

##### Returns

The requested records, decoded.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L1064-L1072)
pub async fn [get\_columns\_by\_key](#method.get_columns_by_key)( \&self, columns: [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>, key\_values: &\[[ShardKeyValue](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/enum.ShardKeyValue.md)\<'\_>], expression: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)>, ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[GetRecordsByColumnResponse](https://docs.kinetica.com/content/api/rust/generated/api/struct.GetRecordsByColumnResponse.md), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Retrieves specific columns with the given key values and filter expression.

##### Arguments

<ul>
  <li>`columns` - The requested columns (which can include expressions). May use “\*” for all columns.</li>
  <li>`key_values` - The key values to use for the lookup, or none</li>
  <li>`expression` - A filter expression</li>
</ul>

##### Returns

The requested records, typed by the response.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/record_retriever.rs#L1086-L1161)
pub async fn [get\_columns\_by\_key\_with\_offset](#method.get_columns_by_key_with_offset)( \&self, columns: [Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[String](https://doc.rust-lang.org/1.98.1/alloc/string/struct.String.html)>, key\_values: &\[[ShardKeyValue](https://docs.kinetica.com/content/api/rust/bulk_inserter_common/enum.ShardKeyValue.md)\<'\_>], expression: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[str](https://doc.rust-lang.org/1.98.1/std/primitive.str.html)>, offset: [i64](https://doc.rust-lang.org/1.98.1/std/primitive.i64.html), ) -> [Result](https://doc.rust-lang.org/1.98.1/core/result/enum.Result.html)\<[GetRecordsByColumnResponse](https://docs.kinetica.com/content/api/rust/generated/api/struct.GetRecordsByColumnResponse.md), [KineticaError](https://docs.kinetica.com/content/api/rust/errors/enum.KineticaError.md)>

Retrieves specific columns with the given key values and filter expression, starting from an offset.

##### Arguments

<ul>
  <li>`columns` - The requested columns</li>
  <li>`key_values` - The key values to use for the lookup, or none</li>
  <li>`expression` - A filter expression</li>
  <li>`offset` - Offset of the record(s) within the result set to return</li>
</ul>

##### Returns

The requested records, typed by the response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.