Add documentation / example about iterating over token ranges

[Jasperav]

I want to add efficient full table scans in Catalytic. According to https://www.scylladb.com/2017/02/13/efficient-full-table-scans-with-scylla-1-6/, an efficient way of doing this is, is by querying with token(id).

There are some tips mentioned in that article how the ranges could be calculated, this involves the amount of cores and cpu’s. I was hoping this information can be queryed or is already available, so creating a method somewhere which returns the efficient token ranges would be easy.

[Lorak-mmk]

@wprzytula Don't we already have that? I'll post your answer from user slack below. To me it looks like there is nothing to do here. Do you agree?

24 Apr at 9:42 AM
Your issue is indeed very interesting.

Token ranges (just as the whole token ring) are not per-keyspace, but global (per-cluster). What the keyspace itself defines is a replication strategy, which, given a token ring, determines which nodes are replicas for a given token.
As a side note, for computing replicas for Network Topology Strategy (which is the default in ScyllaDB now, after SimpleStrategy has been deprecated), per-cluster token ring is not sufficient; one needs to have separate per-datacenter token rings (which Rust driver computes).

You can examine the token ring using the ReplicaLocator entity of the driver. It exposes ring() getter, which yields TokenRing. Then you can iterate over it from the lowest token: TokenRing::iter(), or starting with a particular token: TokenRing::ring_range_full(starting_token).
You can acquire ReplicaLocator and the token ranges the following way:

let cluster_state = session.get_cluster_state();
let locator = cluster_state.replica_locator();
let token_ranges = locator.ring().iter();

Then, how can you obtain replicas for each token range that the token_ranges iterator yields?
By use of ReplicaLocator::replicas_for_token(). You need to feed it with:

• a token belonging to the token range of interest.
• the correct Strategy (replication strategy, most likely NetworkTopologyStrategy),
• restricting datacenter (you probably want to pass None here, as any datacenter is OK in your case),
• a TableSpec - just a pair (keyspace_name, table_name). TableSpec not matter for token ring-based routing; it's used only for tablet routing in ScyllaDB. Thus, you can just pass in empty strings.

What you obtain is a ReplicaSet - an unordered iterable of replicas for the given token. You can either iterate over it (and then collect() to a desired collection) or, if you need order that matches the token ring, first convert it to ReplicasOrdered - an iterable that is ordered according to the global (per-cluster) token ring.I hope this answers your questions. Let me know if anything is not clear yet. Happy coding! ( <-- very much ChatGPT answer style 😉 )

[wprzytula]

@wprzytula Don't we already have that? I'll post your answer from user slack below. To me it looks like there is nothing to do here. Do you agree?

I'm not sure what are the exact requirements of the issue's author (@Jasperav?), but my above answer seems enough to me.

[Lorak-mmk]

I'd vote for first writing an example (and maybe a chapter in the book?) about it, and only then closing the issue.