[v1.38] Document runtime property reindex#427
Open
g-despot wants to merge 6 commits into
Open
Conversation
![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 |
Infrastructure as Code |  0  0  0  0 |
View in Orca |
| Passed |
SAST | 0 0 0 0 |
View in Orca |
| Passed |
Secrets | 0 0 0 0 |
View in Orca |
| Passed |
Vulnerabilities | 0 0 0 0 |
View in Orca |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR documents the v1.38 Preview runtime reindex capability for inverted indexes, adding how-to and reference coverage for REST-only reindex operations while updating related inverted-index guidance.
Changes:
- Adds runtime reindex documentation for add/change/rebuild/cancel/status workflows and endpoint semantics.
- Updates existing collection/indexing pages to replace the old export/recreate-only guidance for v1.38+.
- Updates release/version-related configuration and adds a shared preview admonition.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
versions-config.json |
Bumps local Weaviate version metadata to 1.38.0. |
docusaurus.config.js |
Points Scalar API reference to the v1.38 OpenAPI spec branch. |
docs/weaviate/manage-collections/inverted-index.mdx |
Adds runtime reindex how-to content and MutationGuard note. |
docs/weaviate/manage-collections/collection-operations.mdx |
Updates post-import indexing guidance for v1.38+ runtime reindex. |
docs/weaviate/config-refs/indexing/inverted-index.mdx |
Adds runtime reindex endpoint/reference details and updates old reindex placeholder guidance. |
docs/weaviate/concepts/indexing/inverted-index.md |
Adds conceptual guidance for live reindexing and BlockMax migration. |
_includes/feature-notes/runtime-reindex.mdx |
Adds shared preview caution for runtime reindex. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| These operations cover **inverted indexes only** (`IndexFilterable`, `IndexSearchable`, `IndexRangeFilters`, BM25 algorithm, tokenization). Vector indexes are configured separately — see [Vector configuration](./vector-config.mdx). | ||
|
|
||
| The feature is **REST-only** for the v1.38 Preview — there is no client-library support yet, so the examples below use `curl`. All examples assume `$WEAVIATE` is the cluster URL and `$TOKEN` is an API key with `UPDATE` on `Collections`. For the endpoint list, request-body reference, status values, concurrency rules, error codes, and required permissions, see [References: Runtime reindex](../config-refs/indexing/inverted-index.mdx#runtime-reindex-v138-preview). |
Comment on lines
+397
to
+400
| until curl -fsS "$WEAVIATE/v1/schema/Article/indexes" \ | ||
| | jq -e '.properties[] | select(.name=="body") | ||
| | .indexes[] | select(.type=="searchable") | ||
| | .status == "ready"' > /dev/null |
Comment on lines
+323
to
+326
| | Multi-tenant | omitted | format-only (`rebuild`, `repair`, `enable-rangeable`) | targets all tenants | | ||
| | Multi-tenant | omitted | semantic (`change-tokenization*`, `enable-*`) | targets all tenants (the schema flip is cluster-wide) | | ||
| | Multi-tenant | provided | format-only | targets the named subset | | ||
| | Multi-tenant | provided | semantic | `400` — semantic migrations cannot be sub-scoped | |
|
|
||
| These operations cover **inverted indexes only** (`IndexFilterable`, `IndexSearchable`, `IndexRangeFilters`, BM25 algorithm, tokenization). Vector indexes are configured separately — see [Vector configuration](./vector-config.mdx). | ||
|
|
||
| The feature is **REST-only** for the v1.38 Preview — there is no client-library support yet, so the examples below use `curl`. All examples assume `$WEAVIATE` is the cluster URL and `$TOKEN` is an API key with `UPDATE` on `Collections`. For the endpoint list, request-body reference, status values, concurrency rules, error codes, and required permissions, see [References: Runtime reindex](../config-refs/indexing/inverted-index.mdx#runtime-reindex-v138-preview). |
Comment on lines
+397
to
+400
| until curl -fsS "$WEAVIATE/v1/schema/Article/indexes" \ | ||
| | jq -e '.properties[] | select(.name=="body") | ||
| | .indexes[] | select(.type=="searchable") | ||
| | .status == "ready"' > /dev/null |
Comment on lines
+323
to
+326
| | Multi-tenant | omitted | format-only (`rebuild`, `repair`, `enable-rangeable`) | targets all tenants | | ||
| | Multi-tenant | omitted | semantic (`change-tokenization*`, `enable-*`) | targets all tenants (the schema flip is cluster-wide) | | ||
| | Multi-tenant | provided | format-only | targets the named subset | | ||
| | Multi-tenant | provided | semantic | `400` — semantic migrations cannot be sub-scoped | |
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Reindex a property on a collection (v1.38+) |
| |---|---| | ||
| | `{"filterable":{"enabled":true}}` | Creates a `RoaringSet` bucket and flips `IndexFilterable=true`. | | ||
| | `{"searchable":{"enabled":true,"tokenization":"word"}}` | Creates a BlockMax searchable bucket, sets `Tokenization`, flips `IndexSearchable=true`. Requires `text` / `text[]`. | | ||
| | `{"rangeable":{"enabled":true}}` | Creates a `RoaringSetRange` bucket and flips `IndexRangeFilters=true`. Numeric types only (`int`, `number`, `date`). | |
- Note the status token also needs READ on CollectionsMetadata - Add Authorization header to the status poll-loop example - Disambiguate enable-rangeable as format-only in the multi-tenancy table - Update filtering.md: existing properties can gain a rangeable index from v1.38 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Confirmed against weaviate IsSemanticMigration(): change-algorithm (WAND -> BlockMax) is a semantic migration and cannot be tenant-scoped, while enable-rangeable is intentionally format-only and can be. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 |
Reword user-facing reindex content to drop internal concepts that users shouldn't need to know: storage buckets (RoaringSet/RoaringSetRange/ BlockMax buckets), internal schema-flag names, the schema FSM, replicas/ barrier groups, object storage, task-ID encoding, and finalize/drain timing. Describe observable behavior instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove (v1.38+) / (v1.38 Preview) from the two reindex headings and update all cross-link anchors accordingly. The preview admonition at the start of each section already conveys the version. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
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.
Summary
Documents the new v1.38 Preview runtime-reindex endpoints. Lets users alter inverted-index configuration on a populated collection without restart — add or rebuild filterable / searchable / range indexes, change tokenization, migrate BM25 from WAND to BlockMax — while reads stay available and writes keep flowing.
Replaces the long-standing placeholder "We are working on a re-indexing API… available in a future release" and complements the staged v1.30 BlockMax migration guide.
Companion to weaviate/weaviate#11326 (server PR).
Documentation approach
Rather than a standalone page, the content is distributed across the existing inverted-index pages by altitude, so each topic lives next to the related material readers already navigate to:
manage-collections/inverted-index.mdxgets a new## Reindex a property on a collection (v1.38+)section (add index, change tokenization, migrate BM25, rebuild/repair, cancel, check status) beside the existing enable/drop/tokenization how-tos.config-refs/indexing/inverted-index.mdxgets a## Runtime reindex (v1.38 Preview)reference: endpoints, request-body shapes, status values, concurrency, multi-tenancy rules, error codes, and required permissions.concepts/indexing/inverted-index.mdgets a### Changing an index after importsubsection explaining the non-destructive, restart-safe, schema-flag-as-source-of-truth model.There is no new standalone page and no new sidebar entry — the operations are discoverable from the existing "Inverted index" how-to entry.
What's documented
Two genuinely new REST endpoints, plus a new MutationGuard contract on an existing one:
PUT/v1/schema/{class}/indexes/{property}GET/v1/schema/{class}/indexesDELETE/v1/schema/{class}/properties/{property}/index/{indexName}REST-only for v1.38 Preview. None of the Python / TypeScript / Java / C# / Go clients have shipped typed methods yet — verified against each client's source. Client tabs can land in follow-up PRs as support ships.
Verbs covered
{"filterable":{"enabled":true}}, etc.)textproperty (with the filterable + searchable co-retokenize rule)CANCELLEDvsNO_OPresponse)ready/pending/indexing/failed/cancelled)?tenants=...rules table)(class, property)exclusivity + 32-unit-per-class cap)Files
New
_includes/feature-notes/runtime-reindex.mdx—:::caution Preview — added in v1.38admonition with the v1.38 backup-interaction warning.Updated
docs/weaviate/manage-collections/inverted-index.mdx— new## Reindex a property on a collection (v1.38+)how-to section;:::tipcallout at the top;:::note v1.38+ MutationGuardon the existing "Drop an inverted index" section.docs/weaviate/config-refs/indexing/inverted-index.mdx— new## Runtime reindex (v1.38 Preview)reference; expanded "Drop an inverted index" reference with the explicit REST path and MutationGuard contract; updated the stale "re-indexing API… future release" note.docs/weaviate/concepts/indexing/inverted-index.md— new### Changing an index after importconceptual subsection; updated the BlockMax migration note to point at the runtime endpoint.docs/weaviate/manage-collections/collection-operations.mdx— replaced the "available in a future release" placeholder with a list distinguishing the v1.38+ runtime path from the legacy export/recreate workaround.docs/weaviate/concepts/filtering.md— noted that from v1.38 an existing property can gain a rangeable index via runtime reindex (previously stated as impossible).Test plan
yarn buildclean (only the pre-existing unrelatedhnsw_startup_wait_for_vector_cacheanchor warning remains).weaviate-client, TSweaviate-client, Javaclient6, C#Weaviate.Client, Goweaviate-go-client).:::cautionbackup-interaction warning is still accurate at the time of release.Follow-up
runtime-reindex.mdxwhen the feature GAs.