> ## 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.

# WorkerList

> WorkerList — Kinetica Rust API

[gpudb\_api](https://docs.kinetica.com/content/api/rust/index.md)::<wbr />[worker\_list](https://docs.kinetica.com/content/api/rust/worker_list/index.md)
[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L57-L67)&#x20;

<pre>`pub struct WorkerList { /* private fields */ }`</pre>

A list of worker URLs to use for multi-head operations.The addresses belong to the **connection**, not to this list. A [`Kinetica`](https://docs.kinetica.com/content/api/rust/gpudb/struct.Kinetica) instance discovers each cluster’s rank addresses, applies the connection’s hostname regex to them, and keeps the result per cluster; this struct is a view onto that, held by a bulk inserter or record retriever.It does not resolve or filter addresses of its own. A filter has no coherent meaning here, because it cannot survive a failover: one tuned for a cluster’s addressing may match nothing on the next, and multi-head objects fail over with the connection. Set the regex on the connection instead — see `KineticaOptions::set_hostname_regex` — where it is applied to every cluster as that cluster is discovered.The one choice that is meaningful per object is declining multi-head altogether; see [`WorkerList::empty`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.empty). That names an intent rather than an address, and an intent transfers across clusters where a list of addresses does not.Note entry `i` of this list is rank `i + 1`; the head rank is not a member, and a rank removed from the cluster keeps its slot as `None`. The worker indices in the shard routing table are rank numbers, so compacting the list would silently misroute every rank above the hole.

## Example

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

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

// Use the addresses the connection discovered for its current cluster
let worker_list = WorkerList::from_cluster(&kinetica);

// Or decline multi-head for one inserter/retriever, keeping fail-over
let head_node_only = WorkerList::empty();
```

## Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L77-L274)
impl [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L94-L99)
pub fn [empty](#method.empty)() -> Self

Creates an empty [`WorkerList`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList), which declines multi-head operations for the bulk inserter or record retriever it is given to.That object will route through the head node for its lifetime. The choice is authoritative: it is not undone when the worker list is rebuilt after a failover or a shard rebalance.This is the way to decline multi-head for a single object while keeping the connection’s fail-over. Disabling auto-discovery is not equivalent — it also stops the client discovering the other clusters in an HA ring, so it costs fail-over as well.Nothing inside this crate may use this constructor: it is a caller’s way of expressing an intent, and an internal use would silently pin its own list to head-node-only. Internal code wanting a list with no addresses builds one through [`WorkerList::with_urls`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.with_urls) instead.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L125-L127)
pub fn [from\_cluster](#method.from_cluster)(db: &[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)>) -> Self

Creates a [`WorkerList`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList) from the worker rank addresses the given connection has already discovered for the cluster it is currently on.This reads the connection’s addresses; it does not query the server or re-resolve them. They were filtered through the connection’s hostname regex when that cluster was discovered, so they already reflect it.If the connection has no worker addresses for the current cluster — multi-head is off at the server, or the cluster advertises none this client can use — the list is empty and the object using it operates through the head node.

##### Arguments

<ul>
  <li>`db` - The Kinetica instance whose addresses to use</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L158-L160)
pub fn [is\_multi\_head\_enabled](#method.is_multi_head_enabled)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Whether multi-head operations can be used with this list.

##### Returns

Whether the list names any worker rank.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L175-L177)
pub fn [len](#method.len)(\&self) -> [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)

Returns the number of workers in the list.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L180-L182)
pub fn [is\_empty](#method.is_empty)(\&self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Returns `true` if the worker list is empty.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L194-L196)
pub fn [get](#method.get)(\&self, index: [usize](https://doc.rust-lang.org/1.98.1/std/primitive.usize.html)) -> [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<&[Url](https://docs.rs/url/2.5.7/url/struct.Url.html)>

Gets the URL at the specified index.

##### Arguments

<ul>
  <li>`index` - The index of the worker URL to get (0-based, corresponds to rank-1)</li>
</ul>

##### Returns

The URL at the specified index, or `None` if the rank was removed or the index is out of bounds.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L201-L203)
pub fn [urls](#method.urls)(\&self) -> &[Vec](https://doc.rust-lang.org/1.98.1/alloc/vec/struct.Vec.html)\<[Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[Url](https://docs.rs/url/2.5.7/url/struct.Url.html)>>

Returns a reference to the underlying vector of URLs.`None` entries represent removed worker ranks.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L209-L211)
pub fn [iter](#method.iter)(\&self) -> impl [Iterator](https://doc.rust-lang.org/1.98.1/core/iter/traits/iterator/trait.Iterator.html)\<Item = &[Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[Url](https://docs.rs/url/2.5.7/url/struct.Url.html)>>

Returns an iterator over the URLs in the worker list.This iterator yields references to `Option<Url>`, where `None` represents removed worker ranks.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L218-L220)
pub fn [push](#method.push)(\&mut self, url: [Option](https://doc.rust-lang.org/1.98.1/core/option/enum.Option.html)\<[Url](https://docs.rs/url/2.5.7/url/struct.Url.html)>)

Adds a URL to the worker list.

##### Arguments

<ul>
  <li>`url` - The URL to add, or `None` to add a placeholder for a removed rank</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L227-L229)
pub fn [add](#method.add)(\&mut self, url: [Url](https://docs.rs/url/2.5.7/url/struct.Url.html))

Adds a URL to the worker list (convenience method that wraps in `Some`).

##### Arguments

<ul>
  <li>`url` - The URL to add</li>
</ul>

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L248-L253)
pub fn [to\_url\_strings](#method.to_url_strings)(\&self) -> [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)>

Converts the worker list to a vector of URL strings.This method filters out `None` entries (removed ranks) and returns only the valid URL strings.

##### Never use this for shard routing

The result is **compacted**, so its indices are no longer rank numbers. Routing a sharded record through these indices sends every rank above a removed one to the wrong host. Use [`Self::urls`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.urls) and index by slot, or let the bulk inserter build its rank mapping from the slot positions. This is only safe where any live worker will do — round-robin distribution, health checks, and the like.

##### Returns

A vector of URL strings for all valid (non-removed) workers.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L268-L273)
pub fn [into\_url\_strings](#method.into_url_strings)(self) -> [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)>

Consumes the worker list and returns a vector of URL strings.This method filters out `None` entries (removed ranks) and returns only the valid URL strings.

##### Never use this for shard routing

The result is compacted; see [`Self::to_url_strings`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.to_url_strings) for why that makes it unusable for routing sharded records.

##### Returns

A vector of URL strings for all valid (non-removed) workers.

## Trait Implementations

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L56)
impl [Clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html) for [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L56)
fn [clone](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)(\&self) -> [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

Returns a duplicate of the value. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#tymethod.clone)

1.0.0 (const: [unstable](https://github.com/rust-lang/rust/issues/142757)) · [Source](https://doc.rust-lang.org/1.98.1/src/core/clone.rs.html#245-247)
fn [clone\_from](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)(\&mut self, source: \&Self)

Performs copy-assignment from `source`. [Read more](https://doc.rust-lang.org/1.98.1/core/clone/trait.Clone.html#method.clone_from)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L56)
impl [Debug](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html) for [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L56)
fn [fmt](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html#tymethod.fmt)(\&self, f: \&mut [Formatter](https://doc.rust-lang.org/1.98.1/core/fmt/struct.Formatter.html)\<'\_>) -> [Result](https://doc.rust-lang.org/1.98.1/core/fmt/type.Result.html)

Formats the value using the given formatter. [Read more](https://doc.rust-lang.org/1.98.1/core/fmt/trait.Debug.html#tymethod.fmt)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L71-L75)
impl [Default](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html) for [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

The same as [`WorkerList::empty`](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList#method.empty), which declines multi-head operations. Internal code must not use it, as `empty` says.

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L72-L74)
fn [default](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html#tymethod.default)() -> Self

Returns the “default value” for a type. [Read more](https://doc.rust-lang.org/1.98.1/core/default/trait.Default.html#tymethod.default)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L287)
impl [Eq](https://doc.rust-lang.org/1.98.1/core/cmp/trait.Eq.html) for [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L276-L285)
impl [PartialEq](https://doc.rust-lang.org/1.98.1/core/cmp/trait.PartialEq.html) for [WorkerList](https://docs.kinetica.com/content/api/rust/worker_list/struct.WorkerList.md)

[Source](https://github.com/kineticadb/kinetica-api-rust/blob/master/crates/gpudb-api/src/worker_list.rs#L282-L284)
fn [eq](https://doc.rust-lang.org/1.98.1/core/cmp/trait.PartialEq.html#tymethod.eq)(\&self, other: \&Self) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Two lists are equal when they name the same ranks, holes included.The head-node-only intent is deliberately excluded: this compares addresses, and it is what the rebuild paths use to decide whether a cluster’s addresses have actually changed.

1.0.0 (const: [unstable](https://github.com/rust-lang/rust/issues/143800)) · [Source](https://doc.rust-lang.org/1.98.1/src/core/cmp.rs.html#263)
fn [ne](https://doc.rust-lang.org/1.98.1/core/cmp/trait.PartialEq.html#method.ne)(\&self, other: [\&Rhs](https://doc.rust-lang.org/1.98.1/std/primitive.reference.html)) -> [bool](https://doc.rust-lang.org/1.98.1/std/primitive.bool.html)

Tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason.


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