replikativ / replikativ/scriptum
Allow codec configuration on BranchIndexWriter (currently blocks Lucene suggest fields)
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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