replikativ / replikativ/scriptum

Allow codec configuration on BranchIndexWriter (currently blocks Lucene suggest fields)

Open
#7 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Clojure
Stars
20
Forks
1
Avg merge
1d 9h
Merged PRs (30d)
3

Description

Checked against v0.1.30 (90dbd2a) / Lucene 10.3.2.

Problem

SuggestField
and ContextSuggestField
require a Codec
whose getPostingsFormatForField
returns a CompletionPostingsFormat
(Completion101PostingsFormat
for Lucene 10.3). That codec has to be set on the
IndexWriterConfig
before the IndexWriter
is constructed.

BranchIndexWriter
builds its IndexWriterConfig internally at four sites, and none of them call
setCodec:

Line Enclosing method
328 createOver
402 create
507 open
693 forkLocked

None of the public factories take a codec either; they stop at
create(basePath, branchName, analyzer, cryptoHash).

There is no post-construction escape hatch either.
getIndexWriter().getConfig()
returns a LiveIndexWriterConfig,
where the codec is read-only.

So a SuggestField can be handed to
addDocument(Iterable<? extends IndexableField>)
and will be accepted, but it cannot be indexed in a form
SuggestIndexSearcher
can query.

The read half already works.
openReader()
and openReaderAt(generation)
return a plain DirectoryReader,
which wraps in a SuggestIndexSearcher with no change to scriptum. Per-branch and
historical suggest queries come for free once the write path is unblocked.

Why it fits

Completion postings are ordinary per-segment files, so I would expect COW segment
sharing, fork, snapshot addresses and the merkle content-hash to cover them
unchanged. I have not tested that, and it is the part of this I am least sure of.
Autocomplete you can fork, or query at an older commit, seems like a reasonable
thing to want from a branched index, and ContextSuggestField maps onto
multi-tenant scoping.

Suggested shape

Accept an optional Codec on the create / createOver / open factories and
thread it to all four construction sites, with today's behavior as the default. An
IndexWriterConfig customizer such as a
UnaryOperator<IndexWriterConfig>
would be more general if you prefer that.

forkLocked
is the one I would watch. It builds a fresh config rather than inheriting the
parent's, so if it is missed a fork quietly loses its codec and only fails later,
at query time, on the branch rather than on main.

On the Clojure side this could be an option to
create-index
and open-store-index,
plus a :suggest field type in
add-doc.

lucene-suggest need not become a scriptum dependency. A codec parameter is
enough to let callers bring their own.

Two interactions to watch

  • BranchAwareMergePolicy
    will not merge all-shared segments, so segment count grows with branch and
    commit history. Completion FSTs are held per segment, so a suggest-heavy index
    would feel that as heap growth sooner than an ordinary index does.
  • For store-backed indices,
    warm!
    would want to cover the completion files. Otherwise a cold suggest query pays a
    round trip per file, like any other cold read.

I am happy to put up a PR if this shape sounds right. If you would rather expose
the whole IndexWriterConfig than just the codec, say so and I will follow that
instead.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/java/org/replikativ/scriptum/BranchIndexWriter.java at createOver, create, open, and forkLocked, then trace the public factories that construct their IndexWriterConfig instances. Review the Clojure entry points in src/clojure/scriptum/core.clj, especially create-index and open-store-index. Done means the optional codec reaches every writer configuration while existing defaults remain unchanged, including writers created during forks.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure, java
Domain
backend-api-design, search
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.