Skip to content

[elixir] Add primary key and prefix lookup - #4704

Open
nicolazar wants to merge 1 commit into
apache:mainfrom
nicolazar:feat/elixir-lookup
Open

nicolazar wants to merge 1 commit into
apache:mainfrom
nicolazar:feat/elixir-lookup

Conversation

@nicolazar

@nicolazar nicolazar commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Linked issue: close apache/fluss-rust#462

This PR adds primary key lookups to the Elixir bindings, completing the primary key table support alongside #4628.

Brief change log

Allow Elixir clients to read rows from primary key (KV) tables:

  • Introduce two new modules - Fluss.Lookuper and Fluss.PrefixLookuper, the interfaces for KV table lookups
  • Fluss.Lookuper: lookup/2 by primary key (list or map), returning {:ok, row} or {:ok, nil}; its bang variant raises Fluss.NoResultsError, similar to Ecto.NoResultsError.
  • Fluss.PrefixLookuper: lookup/2 returns every row matching the bucket-key prefix.
  • Allow configuring the five lookup.* config keys on Fluss.Config, as in the python bindings.
  • Keys are validated before reaching core: wrong length, non-key map columns, nil key values, improper lists.

Tests

Integration tests in test/integration/lookup_test.exs, on a real cluster:

  • lookup by list and map key, missing key, lookup!/2, null columns
  • sees overwrites, deletes and partial updates
  • one lookuper shared by 50 concurrent processes
  • composite primary key order, complex types, partitioned tables
  • prefix lookup, including within a partition, and its validation errors

API and Format

New public Elixir API only. No storage format change.

Bind the client's Lookuper and PrefixKeyLookuper so Elixir can read
rows from primary key (KV) tables.

- Introduce `Fluss.Lookuper` and `Fluss.PrefixLookuper`
- Fluss.Lookuper: lookup/2 by primary key (list or map), returning
  {:ok, row} or {:ok, nil}; lookup!/2 raises Fluss.NoResultsError.
- Fluss.PrefixLookuper: lookup/2 returns every row with a bucket-key
  prefix.
- Allow configuring the five lookup.* config keys on Fluss.Config.
- Add integration tests for both lookups, key validation, composite keys,
  partitioned tables and concurrent use.

# Hangs: core retries an unknown bucket leader forever instead of failing.
@tag :skip
test "returns an error after the table is dropped", %{conn: conn, admin: admin} do

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fresh-borzoni: while testing this, it seems that lookups on a dropped table never return, because they are re-enqueued without counting retries (seems like a gap in LookupDispatcher, but I am not too familiar with the code to be 100% sure). I'd expect to get table_not_exist, but the test actually times out, that is why it is skipped for now. I'll remove the tag once the issue is addressed one way or another.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nicolazar Good catch, It's a real gap, but not Elixir-specific and not new: the Java client does the same.
Both clients re-queue a lookup whose leader can't be found, without counting retries. Java only fails fast for a dropped partition.

Keeping the test skipped here is fine. Could you file an issue and link it in the skip comment(TODO or smth)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[elixir] Primary key lookup in KV

2 participants