Controlling fanout
The topology determines which shards contain rows. The fanout component of a query plan specifies how broadly a statement will route:
An
IN predicate on the shard key produces a Route [IN], as shown in Query
planning, and has multi fanout.
Its values may resolve to one shard or several, but the plan is limited to the shards holding those values.
The __neki.fanout setting
Set __neki.fanout for a session to reject SELECT and data-changing
statements whose routing shape exceeds the selected level:
scatter. A statement that exceeds the setting fails instead of running:
single for request paths expected to use a
single-shard routing shape, or multi when a bounded set of destinations is
acceptable. Allow scatter for deliberate whole-group work.
The setting also applies to EXPLAIN (NEKI_PG_PLAN, ANALYZE) because ANALYZE
executes the underlying statement.
This setting does not apply to DDL. Fanout required to maintain reference tables
and GSIs is also exempt.
Choosing where reads run
Read targeting selects which type of Postgres instance serves a session’s read queries. The default target isprimary.
Set __neki.target to use another target:
The following settings control how Neki chooses a
replica or rdonly
instance:
Neki excludes a replica when its lag is unknown or above the maximum allowed
lag. A
require policy can narrow the candidates further. The query fails if no
candidate remains.
These settings cannot change during a transaction. Set them in separate
statements before starting the transaction.
Targeting one shard directly
Direct shard targeting sends data queries to one shard UID without using the data topology to route them.__neki.shard is set:
Neki rejects a schema change while a direct shard target is set because schema
changes run across the cluster rather than on one shard. Use a separate
connection without
__neki.shard to run the change cluster-wide. Publication
DDL and maintenance, privilege, and annotation statements still follow the
normal router path and can run across every shard.
While a shard target is set, a data query cannot also call a router-managed
function such as current_setting, set_config, or nextval. Neki rejects
the statement because it cannot forward the table access and evaluate the
function in the router.
You cannot change __neki.shard during a transaction. Clear the target to
restore normal routing: