docs: runtime property reindex (1.39)#476
Draft
g-despot wants to merge 5 commits into
Draft
Conversation
Add a "Update inverted indexes at runtime" section to the inverted index page covering update_property_index, get_property_indexes, rebuild_property_index and cancel_property_index_task. Call out the two behaviours most likely to trip users up: enabling a searchable index always requires a tokenization argument, and tokenization is a property-level setting, so migrating it on one index also changes what the other index on that property reports. The examples are Python only, since that is the only client with this API so far. The section says so above the first code block, and the new Tabs blocks drop groupId so a single-language tab cannot overwrite the reader's page-wide language selection. The snippets are guarded on the server version so they run on 1.39 and are skipped on the 1.38 image pinned in tests/docker-compose-anon.yml, keeping docs CI green. The guard sits outside the rendered markers and the blocks render with pyindent, so readers see plain copy-pasteable code. Bump that compose image to a released 1.39 to start executing these snippets in CI.
Demonstrate the tokenization change path, which the "Add or change an index" heading promised but only described in prose. The new example changes a searchable index tokenization and then prints both indexes on that property, so the effect on the filterable index is visible rather than asserted. This is the case with the silent consequence for filter matching, so it is worth showing. Rework the admonitions so severity tracks risk. The missing tokenization argument fails immediately with a self-describing error, so it is a note. The tokenization change is silent and alters how live filters match, so it keeps the caution and its title now states the consequence instead of the mechanism. Also: use US English for "canceled", standardize on "change" rather than mixing in "migrate", say that the call returns before the index is built and point to the status section for polling, refer to each index's status rather than its state, move the tenants restriction for adding and changing into the Add section, and link the forward reference to the Drop section. Note that pending and indexing can pass too quickly to observe on a small collection, and that indexing can persist briefly after the work finishes while the new index is swapped in, so readers wait for ready.
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Secrets |  0  0  0  0 |
View in Orca |
Move client method names and client parameter names out of the prose and into the code blocks, where they belong. The text now describes each operation in plain words (adding or changing an index, rebuilding, canceling a running rebuild, listing a collection's indexes, limiting a rebuild to specific tenants) and lets the Python examples show the exact calls. Keep the values that are the same across every client and are genuine API or server concepts: the NO_OP status, the pending, indexing and ready lifecycle states, task IDs, tenants, tokenization, and the searchable and filterable index types. Reword the progress sentence to avoid a language-specific null literal while keeping progress and status as concepts. Code blocks are unchanged.
The client PR now exports a PropertyIndexType enum, so the four runtime reindex blocks pass the index type as PropertyIndexType.SEARCHABLE, PropertyIndexType.FILTERABLE and PropertyIndexType.RANGE_FILTERS instead of string literals, and import the enum alongside the other config classes. Each rendered block imports it so the example stays copy-pasteable on its own. The read-side status check keeps its string comparison: the returned index type is still a plain string, and it compares equal to the enum member because the enum subclasses str, so the assertion holds either way. The enum import stays inside the server-version guard, so on the client version docs CI pins today, which predates the enum, the guarded block is never entered and the file still imports and runs. The pre-existing v1.36 drop snippet keeps its string literals for the same reason: it runs unguarded and its import must resolve on the pinned client.
The Python client scoped the reindex type names to inverted indexes, so the four runtime reindex blocks import and use InvertedIndexType in place of PropertyIndexType, and their inline output comments now show InvertedIndexTaskStatus and InvertedIndexState, which is what the client prints. The enum members are unchanged, so the calls are the same shape. The import stays inside the server-version guard, so on the client version docs CI pins today, which has neither name, the guarded block is never entered and the file still imports and runs. The v1.36 drop snippet keeps its string literals for that reason, and the prose is unchanged because it never named a client type.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the runtime property reindex API: add, change, rebuild and check inverted indexes on an existing property without recreating the collection.
Draft: depends on weaviate/weaviate#12252 (server) and weaviate/weaviate-python-client#2098 (client), both unmerged.
Update inverted indexes at runtimesection ininverted-index.mdx, placed above the existing v1.36 Drop section so the page reads add, check, rebuild, drop.manage-data.collections.py, all verified against a 1.39.0-dev server.groupIdso a single-option group cannot overwrite the reader's page-wide language choice.Docs CI stays green today. The new blocks sit behind a server-version guard placed outside the snippet markers and rendered with
pyindent, so readers see flat copy-pasteable Python with no scaffolding. Verified in both directions: skipped with zero output on 1.38.0, fully executed on 1.39.0-dev.At GA: bump
tests/docker-compose-anon.yml:11to a released 1.39 and all four blocks start executing. No snippet edits needed.Two things the docs work surfaced that are worth fixing client-side before ship:
Property may not exist!, which contradicts the accurate server message printed immediately below it.tokenization=, costing a round trip to learn something the client could infer from the property or reject locally.Site build passes.