From da77b9e88885328aaac21dd277f6c785baf5af66 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:46:32 +0200
Subject: [PATCH 01/12] docs: reference updates for Weaviate 1.39
Remove the schema_tx metrics, which were deleted from core in 1.39.
Promote the Boost API note from preview to generally available, and
rename the now-misleading BoostPreview import alias to BoostNote across
the five pages that render it.
---
_includes/feature-notes/boost.mdx | 3 +--
docs/deploy/configuration/monitoring.md | 8 --------
docs/weaviate/search/bm25.md | 4 ++--
docs/weaviate/search/boost.md | 4 ++--
docs/weaviate/search/hybrid.md | 4 ++--
docs/weaviate/search/rerank.md | 4 ++--
docs/weaviate/search/similarity.md | 4 ++--
7 files changed, 11 insertions(+), 20 deletions(-)
diff --git a/_includes/feature-notes/boost.mdx b/_includes/feature-notes/boost.mdx
index 68167df1..b522d781 100644
--- a/_includes/feature-notes/boost.mdx
+++ b/_includes/feature-notes/boost.mdx
@@ -1,3 +1,2 @@
-:::caution Preview — added in `v1.38`
-This is a preview feature. The API may change in future releases.
+:::info Added in `v1.39`
:::
diff --git a/docs/deploy/configuration/monitoring.md b/docs/deploy/configuration/monitoring.md
index 4ecf2dc1..5268dc34 100644
--- a/docs/deploy/configuration/monitoring.md
+++ b/docs/deploy/configuration/monitoring.md
@@ -282,14 +282,6 @@ These metrics track Write-Ahead Log (WAL) recovery operations during startup.
| `schema_reads_leader_seconds` | Duration of schema reads that are passed to the leader | `type` | `Summary` |
| `schema_wait_for_version_seconds` | Duration of waiting for a schema version to be reached | `type` | `Summary` |
-#### Schema transactions (deprecated)
-
-| Metric | Description | Labels | Type |
-| ---------------------------- | --------------------------------------------------------------------------------------- | --------------------- | --------- |
-| `schema_tx_opened_total` | Total number of opened schema transactions | `ownership` | `Counter` |
-| `schema_tx_closed_total` | Total number of closed schema transactions. A close must be either successful or failed | `ownership`, `status` | `Counter` |
-| `schema_tx_duration_seconds` | Mean duration of a tx by status | `ownership`, `status` | `Summary` |
-
#### RAFT metrics (internal)
| Metric | Description | Labels | Type |
diff --git a/docs/weaviate/search/bm25.md b/docs/weaviate/search/bm25.md
index 414e6f85..8acf000c 100644
--- a/docs/weaviate/search/bm25.md
+++ b/docs/weaviate/search/bm25.md
@@ -16,7 +16,7 @@ import GoCode from '!!raw-loader!/\_includes/code/howto/go/docs/mainpkg/search-b
import JavaV6Code from "!!raw-loader!/\_includes/code/java-v6/src/test/java/SearchKeywordTest.java";
import CSharpCode from "!!raw-loader!/\_includes/code/csharp/SearchKeywordTest.cs";
import GQLCode from '!!raw-loader!/\_includes/code/howto/search.bm25.gql.py';
-import BoostPreview from '/_includes/feature-notes/boost.mdx';
+import BoostNote from '/_includes/feature-notes/boost.mdx';
`Keyword` search, also called "BM25 (Best match 25)" or "sparse vector" search, returns objects that have the highest BM25F scores.
@@ -767,7 +767,7 @@ Set the tokenization method to `trigram` at the property level when creating you
## Soft-rank with Boost
-
+
Keyword (BM25) queries accept an optional `boost` argument that promotes or demotes matching documents without removing them — useful for biasing results by recency, popularity, a soft filter, or another property. Matching documents move up. Everything else stays in the results but ranks lower.
diff --git a/docs/weaviate/search/boost.md b/docs/weaviate/search/boost.md
index 7fe9c60c..3cf663f2 100644
--- a/docs/weaviate/search/boost.md
+++ b/docs/weaviate/search/boost.md
@@ -10,9 +10,9 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock';
import PyCode from '!!raw-loader!/_includes/code/howto/search.boost.py';
-import BoostPreview from '/_includes/feature-notes/boost.mdx';
+import BoostNote from '/_includes/feature-notes/boost.mdx';
-
+
**Boost** soft-ranks search results — promote or demote matching documents without removing them from the result set. Matching documents move up. Non-matching documents stay in the results but rank lower.
diff --git a/docs/weaviate/search/hybrid.md b/docs/weaviate/search/hybrid.md
index 0956af11..1a522821 100644
--- a/docs/weaviate/search/hybrid.md
+++ b/docs/weaviate/search/hybrid.md
@@ -16,7 +16,7 @@ import GoCode from '!!raw-loader!/\_includes/code/howto/go/docs/mainpkg/search-h
import JavaV6Code from "!!raw-loader!/\_includes/code/java-v6/src/test/java/SearchHybridTest.java";
import CSharpCode from "!!raw-loader!/\_includes/code/csharp/SearchHybridTest.cs";
import GQLCode from '!!raw-loader!/\_includes/code/howto/search.hybrid.gql.py';
-import BoostPreview from '/_includes/feature-notes/boost.mdx';
+import BoostNote from '/_includes/feature-notes/boost.mdx';
`Hybrid` search combines the results of a vector search and a keyword (BM25F) search by fusing the two result sets.
@@ -1041,7 +1041,7 @@ import TokenizationNote from '/\_includes/tokenization.mdx'
## Soft-rank with Boost
-
+
Hybrid queries accept an optional `boost` argument that promotes or demotes matching documents without removing them — useful for biasing results by recency, popularity, a soft filter, or another property.
diff --git a/docs/weaviate/search/rerank.md b/docs/weaviate/search/rerank.md
index 2dac8f57..df7b5b54 100644
--- a/docs/weaviate/search/rerank.md
+++ b/docs/weaviate/search/rerank.md
@@ -16,7 +16,7 @@ import SimilarityPyCode from '!!raw-loader!/_includes/code/howto/search.similari
import SimilarityPyCodeV3 from '!!raw-loader!/_includes/code/howto/search.similarity-v3.py';
import SimilarityTSCode from '!!raw-loader!/_includes/code/howto/search.similarity.ts';
import GoCode from '!!raw-loader!/_includes/code/howto/go/docs/mainpkg/search-rerank_test.go';
-import BoostPreview from '/_includes/feature-notes/boost.mdx';
+import BoostNote from '/_includes/feature-notes/boost.mdx';
Reranking modules reorder the search result set according to a different set of criteria or a different (e.g. more expensive) algorithm.
@@ -199,7 +199,7 @@ The response should look like this:
## Soft-rank with Boost
-
+
For lightweight result reordering based on filters, property values, or time / numeric decay — without calling an external rerank model — use [Boost](./boost.md). Rerank and Boost can be used independently. Pick rerank when you need a smarter model to re-rank the top-N, and Boost when you want to bias by simple signals already on the objects.
diff --git a/docs/weaviate/search/similarity.md b/docs/weaviate/search/similarity.md
index 5a4c2fe9..5a15583e 100644
--- a/docs/weaviate/search/similarity.md
+++ b/docs/weaviate/search/similarity.md
@@ -15,7 +15,7 @@ import TSCode from '!!raw-loader!/\_includes/code/howto/search.similarity.ts';
import GoCode from '!!raw-loader!/\_includes/code/howto/go/docs/mainpkg/search-similarity_test.go';
import JavaV6Code from "!!raw-loader!/\_includes/code/java-v6/src/test/java/SearchSimilarityTest.java";
import CSharpCode from "!!raw-loader!/\_includes/code/csharp/SearchSimilarityTest.cs";
-import BoostPreview from '/_includes/feature-notes/boost.mdx';
+import BoostNote from '/_includes/feature-notes/boost.mdx';
Vector search returns the objects with most similar vectors to that of the query.
@@ -719,7 +719,7 @@ A larger candidate set (higher top-level `limit`) gives MMR more results to choo
## Soft-rank with Boost
-
+
Vector search queries accept an optional `boost` argument that promotes or demotes matching documents without removing them — useful for biasing results by recency, popularity, a soft filter, or another property. Matching documents move up. Everything else stays in the results but ranks lower.
From 9a08110ebba52f11a11aca329a38a849a008ee73 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Sun, 19 Jul 2026 21:59:57 +0200
Subject: [PATCH 02/12] Document HNSW snapshot automation and env var
deprecation in v1.39
In v1.39 the HNSW commit log compactor owns the full on-disk lifecycle of
the vector index. Snapshots are always created and managed automatically,
and the five PERSISTENCE_HNSW_SNAPSHOT_* environment variables are inert
no-ops that log a startup warning when set.
Docs serve the latest three supported minors, so the pre-v1.39
configuration guidance is retained and scoped to v1.31 through v1.38
rather than removed.
- configuration/hnsw-snapshots.md: lead with the v1.39 behavior and the
list of ignored variables; move the existing configuration reference
into a section scoped to earlier versions.
- concepts/storage.md: describe snapshots as part of the storage engine
rather than an opt-in speedup, cover the streaming on-disk merge and
the crash-safety mechanisms, and scope the previous conditional
creation and snapshot fallback behavior to earlier versions.
- env-vars/index.md: mark the five variables deprecated in v1.39 while
preserving what they did for readers on earlier versions.
- feature-notes/hnsw-snapshots.mdx: note the v1.39 change on both pages
that consume the include.
---
_includes/feature-notes/hnsw-snapshots.mdx | 1 +
docs/deploy/configuration/env-vars/index.md | 10 ++---
docs/weaviate/concepts/storage.md | 26 +++++-------
docs/weaviate/configuration/hnsw-snapshots.md | 40 ++++++++++++++-----
4 files changed, 48 insertions(+), 29 deletions(-)
diff --git a/_includes/feature-notes/hnsw-snapshots.mdx b/_includes/feature-notes/hnsw-snapshots.mdx
index ff9190c5..d8dd6042 100644
--- a/_includes/feature-notes/hnsw-snapshots.mdx
+++ b/_includes/feature-notes/hnsw-snapshots.mdx
@@ -1,2 +1,3 @@
:::info Added in `v1.31`
+Starting in `v1.39`, HNSW snapshots are created and managed automatically, and are no longer configurable.
:::
diff --git a/docs/deploy/configuration/env-vars/index.md b/docs/deploy/configuration/env-vars/index.md
index e5cca50b..037cf00c 100644
--- a/docs/deploy/configuration/env-vars/index.md
+++ b/docs/deploy/configuration/env-vars/index.md
@@ -83,11 +83,11 @@ import APITable from '@site/src/components/APITable';
| `OPERATIONAL_MODE` | Sets the [mode of operation](../status.md#operational-modes) for the instance. Options: `READ_WRITE` (default), `READ_ONLY`, `WRITE_ONLY`, `SCALE_OUT`. Limits available operations based on the mode selected. | `string` | `READ_WRITE` |
| `ORIGIN` | Set the http(s) origin for Weaviate | `string - HTTP origin` | `https://my-weaviate-deployment.com` |
| `PERSISTENCE_DATA_PATH` | Path to the Weaviate data store.
[Note about file systems and performance](/weaviate/concepts/resources.md#file-system). | `string - file path` | `/var/lib/weaviate`
Defaults to `./data`|
-| `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` | If set, [HNSW snapshotting](/weaviate/concepts/storage.md#persistence-and-crash-recovery) will be disabled. Default: `false` (enabled) as of `v1.36`; `true` (disabled) in `v1.31`–`v1.35`
Added in `v1.31` | `boolean` | `false` |
-| `PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS` | The minimum time in seconds that must pass before the next snapshot is created. Default: `21600` seconds (6 hours)
Added in `v1.31` | `string - number` | `3600` |
-| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER` | The minimum number of new commit log files created since the last snapshot. Default: `1`
Added in `v1.31` | `string - number` | `100` |
-| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE` | The minimum total size of new commit logs (as a percentage of the previous snapshot's size) required to trigger a new snapshot. Default: `5` (meaning 5% of the previous snapshot's size in new commit logs)
Added in `v1.31` | `string - number` | `15` |
-| `PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP` | If set, Weaviate will try to create a new snapshot during startup if there are changes in the commit log since the last snapshot. If there are no changes, then the existing snapshot will be loaded. Default: `true`
Added in `v1.31` | `boolean` | `false` |
+| `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: if set, HNSW snapshotting will be disabled. Default: `false` (enabled) as of `v1.36`; `true` (disabled) in `v1.31`–`v1.35`
Added in `v1.31` | `boolean` | `false` |
+| `PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum time in seconds that must pass before the next snapshot is created. Default: `21600` seconds (6 hours)
Added in `v1.31` | `string - number` | `3600` |
+| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum number of new commit log files created since the last snapshot. Default: `1`
Added in `v1.31` | `string - number` | `100` |
+| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum total size of new commit logs (as a percentage of the previous snapshot's size) required to trigger a new snapshot. Default: `5` (meaning 5% of the previous snapshot's size in new commit logs)
Added in `v1.31` | `string - number` | `15` |
+| `PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: if set, Weaviate will try to create a new snapshot during startup if there are changes in the commit log since the last snapshot. If there are no changes, then the existing snapshot will be loaded. Default: `true`
Added in `v1.31` | `boolean` | `false` |
| `PERSISTENCE_HNSW_MAX_LOG_SIZE` | Maximum size of the HNSW [write-ahead-log](/weaviate/concepts/storage.md#hnsw-vector-index-storage). Increase this to improve log compaction efficiency, or decrease to reduce memory requirements. Default: 500MiB | `string` | `4GiB` (IEC units), `4GB` (SI units), `4000000000` (bytes) |
| `PERSISTENCE_LSM_ACCESS_STRATEGY` | Function used to access disk data in virtual memory. Default: `mmap` | `string` | `mmap` or `pread` |
| `PERSISTENCE_LSM_MAX_SEGMENT_SIZE` | Maximum size of a segment in the [LSM store](/weaviate/concepts/storage.md#object-and-inverted-index-store). Set this to limit disk usage spikes during compaction to ~2x the segment size. Default: no limit | `string` | `4GiB` (IEC units), `4GB` (SI units), `4000000000` (bytes) |
diff --git a/docs/weaviate/concepts/storage.md b/docs/weaviate/concepts/storage.md
index 607330f5..4ce2936e 100644
--- a/docs/weaviate/concepts/storage.md
+++ b/docs/weaviate/concepts/storage.md
@@ -101,7 +101,7 @@ For the HNSW vector index, the Write-Ahead-Log (WAL) is a critical component for
The entire HNSW index state can be reconstructed by replaying these WAL entries.
-For very large indexes of tens or hundreds of millions of objects, this can be time-consuming. If you have a large index and you want to speed up the startup time, you can use the **[HNSW snapshots](../configuration/hnsw-snapshots.md)** feature.
+For very large indexes of tens or hundreds of millions of objects, this can be time-consuming. To avoid replaying the entire WAL on every restart, Weaviate periodically writes **[HNSW snapshots](../configuration/hnsw-snapshots.md)**.
### HNSW snapshots
@@ -109,27 +109,23 @@ import HnswSnapshots from '/_includes/feature-notes/hnsw-snapshots.mdx';
-For very large HNSW vector indexes, HNSW snapshots can significantly reduce the startup time.
+For very large HNSW vector indexes, HNSW snapshots significantly reduce the startup time.
-A snapshot represents a point-in-time state of the HNSW index. When Weaviate starts, if a valid snapshot exists, it will be loaded into memory first. This significantly reduces startup time, as the number of WAL entries that need to be processed, as only the changes made after the snapshot was taken need to be replayed from the WAL.
+A snapshot represents a point-in-time state of the HNSW index. When Weaviate starts, if a snapshot exists, it is loaded first, and only the changes made after the snapshot was taken are replayed from the WAL. This significantly reduces startup time, because the number of WAL entries that have to be processed no longer grows with the age of the index.
-If a snapshot cannot be loaded for any reason, it is safely removed, and Weaviate falls back to the traditional method of loading the full commit log from the beginning, ensuring resilience.
+The WAL is still used to persist every change immediately, guaranteeing that any acknowledged write is durable. Even with a fresh snapshot, the server typically still has to load at least one subsequent commit log file.
-Snapshots can be created at startup and periodically based on time passed or changes in the commit log.
+Starting in `v1.39`, snapshots are part of how the vector index is stored rather than an optional speedup, and Weaviate manages them automatically. A background compactor owns the on-disk lifecycle of the index: it converts each newly flushed commit log into a sorted file, merges sorted files together, and writes a new snapshot when doing so is worthwhile. Snapshot and commit log files live in the same directory, and a snapshot replaces the files it covers rather than duplicating them, which keeps the disk footprint proportional to the size of the index.
-Weaviate will try to create a new snapshot during startup if there are changes in the commit log since the last snapshot. If there are no changes, then the existing snapshot will be loaded.
+Because the merge reads its inputs as sorted streams from disk, only the most recently flushed commit log is processed in memory. That step has a fixed cost regardless of how large the graph is, so snapshot creation no longer requires enough memory to hold the previous snapshot plus the commit log delta.
-A snapshot will also be created if the corresponding conditions are met, meaning the specified time interval has passed and a sufficient number of new commits exist. This is handled by the same background process that manages commit log combining and condensing, ensuring stability as the commit logs used for snapshot creation are not mutable during this process.
+Weaviate protects this on-disk state in several ways. New files are written to a temporary path and atomically renamed into place, so an interrupted write can never be mistaken for a complete file, and orphaned temporary files are cleaned up on the next startup. Snapshots are stored in a checksummed block format. If a commit log file has a torn tail after a crash, it is truncated back to its last valid entry, and a compacted segment that cannot be read in full is dropped in favor of the snapshot and the remaining clean segments.
-Each new HNSW snapshot is based on the previous snapshot and newer (delta) commit logs.
+See **[the HNSW snapshots configuration](../configuration/hnsw-snapshots.md)** for version-specific details.
-It's important to note that even with a fresh snapshot, the server typically still has to load at least one subsequent commit log file.
-
-The WAL is still used to persist every change immediately, guaranteeing that any acknowledged write is durable. Over time, the append-only WAL will contain redundant information for operations occurring after the last snapshot. A background process continuously compacts these newer WAL files, removing redundant information. This, combined with snapshotting, keeps the disk footprint manageable and startup times fast.
-
-See **[the HNSW snapshots configuration](../configuration/hnsw-snapshots.md)** for more details on how to configure this feature.
-
-Starting in `v1.36`, HNSW snapshots are enabled by default. In `v1.31` through `v1.35`, they are disabled by default.
+:::note Behavior before `v1.39`
+In `v1.31` through `v1.38`, snapshots are an optional feature layered on top of the commit log, and are configured with the `PERSISTENCE_HNSW_SNAPSHOT_*` environment variables. They are enabled by default starting in `v1.36`, and disabled by default in `v1.31` through `v1.35`. In these versions, Weaviate creates a snapshot at startup if the commit log changed since the last snapshot, and periodically once a configured time interval has passed and enough new commit log data has accumulated. If a snapshot cannot be loaded, it is removed and Weaviate falls back to loading the full commit log from the beginning. In `v1.39` and later, a snapshot that cannot be read is a startup error instead, because the commit logs it covers no longer exist as a separate copy.
+:::
## Conclusions
diff --git a/docs/weaviate/configuration/hnsw-snapshots.md b/docs/weaviate/configuration/hnsw-snapshots.md
index 9db38efb..85479f8d 100644
--- a/docs/weaviate/configuration/hnsw-snapshots.md
+++ b/docs/weaviate/configuration/hnsw-snapshots.md
@@ -2,29 +2,51 @@
title: HNSW Snapshots
sidebar_position: 47
sidebar_label: HNSW Snapshots
-description: Learn about HNSW snapshots in Weaviate for faster startup times and how to manage them.
+description: Learn how Weaviate uses HNSW snapshots for faster startup times, and how they were configured in versions before v1.39.
---
import HnswSnapshots from '/_includes/feature-notes/hnsw-snapshots.mdx';
-HNSW (Hierarchical Navigable Small World) snapshots can significantly reduce startup times for instances with large vector indexes.
-
-HNSW snapshotting is **enabled by default** starting in `v1.36`. To disable it, set `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` to `true`.
-
-In versions prior to `v1.36`, HNSW snapshotting is disabled by default. Set `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` to `false` to enable it.
+HNSW (Hierarchical Navigable Small World) snapshots significantly reduce startup times for instances with large vector indexes.
:::info Concepts: HNSW snapshots
See this [concepts page](../concepts/storage.md#hnsw-snapshots) for a detailed description.
:::
-## Configuring snapshot creation
+## Snapshots in `v1.39` and later
+
+Starting in `v1.39`, HNSW snapshots are always enabled and are not configurable.
+
+The commit log compactor owns the on-disk lifecycle of the vector index, and snapshots are one of the file formats it produces. Weaviate creates and maintains them automatically, so there is nothing to enable, disable, schedule, or tune.
+
+### Environment variables that no longer have an effect
+
+The following environment variables are still recognized, so existing deployments continue to start without a configuration error. However, they are ignored:
+
+- `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS`
+- `PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS`
+- `PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP`
+- `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER`
+- `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE`
+
+If any of these variables is set, Weaviate logs a warning at startup that names the variable and states that it has no effect and will be removed in a future version. Variables that are not set produce no warning. To clear the warnings, remove the variables from your deployment configuration.
+
+Setting the equivalent options in a YAML or JSON configuration file is also accepted and also ignored, but it does not produce a startup warning.
+
+## Configuring snapshot creation in versions before `v1.39`
+
+:::note
+This section applies to `v1.31` through `v1.38` only. In `v1.39` and later, the environment variables below are ignored.
+:::
+
+In these versions, HNSW snapshotting is an optional feature layered on top of the commit log, and the following environment variables control it.
-Set the following optional environment variables to configure the snapshotting behavior.
+HNSW snapshotting is **enabled by default** starting in `v1.36`. To disable it, set `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` to `true`. In versions prior to `v1.36`, HNSW snapshotting is disabled by default. Set `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` to `false` to enable it.
:::note
-Before creating a new snapshot, the previous snapshot and the commit log difference need to be loaded into memory. Make sure you have enough memory to accommodate this process.
+Before creating a new snapshot, the previous snapshot and the commit log difference need to be loaded into memory. Make sure you have enough memory to accommodate this process. This requirement does not apply in `v1.39` and later, where snapshots are merged from disk as a stream.
:::
### Snapshot on startup
From ea6236e4ef7540cd04cff07b5c3c973a0045196c Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:12:53 +0200
Subject: [PATCH 03/12] Correct corrupt segment recovery description in storage
concepts
The v1.39 crash-safety paragraph said a compacted segment that cannot be
read in full is dropped in favor of the snapshot and the remaining clean
segments. That is not what the loader does. For both raw commit logs and
compacted .sorted/.condensed segments it calls truncateToLastValidRecord,
keeping every record written before the corruption and leaving the file
valid for later compaction. Only the damaged tail is lost.
The two outcomes differ in recall, so describe the retention explicitly
and phrase both cases as the single mechanism they actually are.
Note that the struct comment at compact/loader.go:73-74 and the matching
one at hnsw/startup.go:101-102 still describe the discard behavior and
contradict the implementation. Tracked separately on the core side.
---
docs/weaviate/concepts/storage.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/weaviate/concepts/storage.md b/docs/weaviate/concepts/storage.md
index 4ce2936e..f8a4a383 100644
--- a/docs/weaviate/concepts/storage.md
+++ b/docs/weaviate/concepts/storage.md
@@ -119,7 +119,7 @@ Starting in `v1.39`, snapshots are part of how the vector index is stored rather
Because the merge reads its inputs as sorted streams from disk, only the most recently flushed commit log is processed in memory. That step has a fixed cost regardless of how large the graph is, so snapshot creation no longer requires enough memory to hold the previous snapshot plus the commit log delta.
-Weaviate protects this on-disk state in several ways. New files are written to a temporary path and atomically renamed into place, so an interrupted write can never be mistaken for a complete file, and orphaned temporary files are cleaned up on the next startup. Snapshots are stored in a checksummed block format. If a commit log file has a torn tail after a crash, it is truncated back to its last valid entry, and a compacted segment that cannot be read in full is dropped in favor of the snapshot and the remaining clean segments.
+Weaviate protects this on-disk state in several ways. New files are written to a temporary path and atomically renamed into place, so an interrupted write can never be mistaken for a complete file, and orphaned temporary files are cleaned up on the next startup. Snapshots are stored in a checksummed block format. If a file cannot be read in full, whether it is a commit log with a torn tail after a crash or a compacted segment damaged on disk, it is truncated back to its last valid entry. The entries written before the damage are retained, and the file becomes valid again so that later compaction can read it. Only the damaged tail is lost, and it is unrecoverable in any case.
See **[the HNSW snapshots configuration](../configuration/hnsw-snapshots.md)** for version-specific details.
From 9e2a168fa2accc54a5da0e423e52d638adbb8fc8 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:14:44 +0200
Subject: [PATCH 04/12] Reword the HNSW Snapshots configuration card
The card read "Configure HNSW index snapshots for faster recovery and
startup." There is nothing to configure in v1.39, but the page still
serves v1.37 and v1.38 readers who can configure it, so the description
now leads with the outcome instead of the action and reads correctly for
both audiences.
Keeps the imperative benefit-first voice of the neighbouring cards
("Reduce memory usage with...", "Enable the built-in..."), and drops the
restatement of the card title, which the title already supplies.
---
docs/weaviate/configuration/index.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/weaviate/configuration/index.mdx b/docs/weaviate/configuration/index.mdx
index 40bc472d..3177eca4 100644
--- a/docs/weaviate/configuration/index.mdx
+++ b/docs/weaviate/configuration/index.mdx
@@ -28,7 +28,7 @@ export const configOpsData = [
{
title: "HNSW Snapshots",
description:
- "Configure HNSW index snapshots for faster recovery and startup.",
+ "Speed up startup and recovery for instances with large vector indexes.",
link: "/weaviate/configuration/hnsw-snapshots",
icon: "fas fa-camera",
},
From 4bad93ce961cc86fe644f89b85058ef7199480d6 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Sun, 19 Jul 2026 22:23:06 +0200
Subject: [PATCH 05/12] Apply editor feedback to the v1.39 HNSW snapshot docs
Blocking items:
- Move the v1.39 startup-failure behavior out of the historical note and
into the main durability prose. It was the last sentence of a box
titled "Behavior before v1.39", which told v1.39 readers to skip the
highest-consequence fact in the release.
- Split the durability paragraph in three so commit logs and snapshots
are not conflated. Commit logs, including compacted ones, self-heal by
truncation; snapshots are never truncated or repaired and an unreadable
one fails the index load.
- Stop calling HNSW compaction output a "segment", which contradicts
"the vector index does not use segmentation" earlier on the same page.
Vocabulary is now commit log, compacted commit log, snapshot, compactor.
- Replace en dashes in the env-var rows with "through", matching the
other two files.
Also:
- Compound title on the feature-note include, per the rq-8bit precedent.
- Halve the repeated boilerplate in the five env-var rows and point the
historical half at a new stable anchor on the pre-v1.39 section, so
readers on earlier versions land on the part that applies to them.
- Drop "periodically" from the snapshot lead-in (compaction is driven by
the compactor, not a timer) and stop framing a snapshot as conditional.
- Retitle both scoping notes to name v1.31 through v1.38 explicitly,
since snapshots did not exist before v1.31.
- Add a caution to the configuration page covering the fail-to-start
behavior, which every deprecated env-var row links to.
- Name the configuration file that silently accepts these settings.
The recovery advice was verified against the compactor deleting its
input files after a successful snapshot write, and the loader filtering
covered commit logs, which together confirm no local copy survives.
---
_includes/feature-notes/hnsw-snapshots.mdx | 4 +++-
docs/deploy/configuration/env-vars/index.md | 10 +++++-----
docs/weaviate/concepts/storage.md | 18 +++++++++++-------
docs/weaviate/configuration/hnsw-snapshots.md | 12 ++++++++----
4 files changed, 27 insertions(+), 17 deletions(-)
diff --git a/_includes/feature-notes/hnsw-snapshots.mdx b/_includes/feature-notes/hnsw-snapshots.mdx
index d8dd6042..4d7fb6b8 100644
--- a/_includes/feature-notes/hnsw-snapshots.mdx
+++ b/_includes/feature-notes/hnsw-snapshots.mdx
@@ -1,3 +1,5 @@
-:::info Added in `v1.31`
+:::info Added in `v1.31` · Changed in `v1.39`
+
Starting in `v1.39`, HNSW snapshots are created and managed automatically, and are no longer configurable.
+
:::
diff --git a/docs/deploy/configuration/env-vars/index.md b/docs/deploy/configuration/env-vars/index.md
index 037cf00c..74f83efe 100644
--- a/docs/deploy/configuration/env-vars/index.md
+++ b/docs/deploy/configuration/env-vars/index.md
@@ -83,11 +83,11 @@ import APITable from '@site/src/components/APITable';
| `OPERATIONAL_MODE` | Sets the [mode of operation](../status.md#operational-modes) for the instance. Options: `READ_WRITE` (default), `READ_ONLY`, `WRITE_ONLY`, `SCALE_OUT`. Limits available operations based on the mode selected. | `string` | `READ_WRITE` |
| `ORIGIN` | Set the http(s) origin for Weaviate | `string - HTTP origin` | `https://my-weaviate-deployment.com` |
| `PERSISTENCE_DATA_PATH` | Path to the Weaviate data store.
[Note about file systems and performance](/weaviate/concepts/resources.md#file-system). | `string - file path` | `/var/lib/weaviate`
Defaults to `./data`|
-| `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: if set, HNSW snapshotting will be disabled. Default: `false` (enabled) as of `v1.36`; `true` (disabled) in `v1.31`–`v1.35`
Added in `v1.31` | `boolean` | `false` |
-| `PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum time in seconds that must pass before the next snapshot is created. Default: `21600` seconds (6 hours)
Added in `v1.31` | `string - number` | `3600` |
-| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum number of new commit log files created since the last snapshot. Default: `1`
Added in `v1.31` | `string - number` | `100` |
-| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: the minimum total size of new commit logs (as a percentage of the previous snapshot's size) required to trigger a new snapshot. Default: `5` (meaning 5% of the previous snapshot's size in new commit logs)
Added in `v1.31` | `string - number` | `15` |
-| `PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP` | **Deprecated in `v1.39`.** [HNSW snapshots](/weaviate/configuration/hnsw-snapshots.md) are now always enabled and managed automatically, so this variable is ignored and setting it logs a startup warning. In `v1.31`–`v1.38`: if set, Weaviate will try to create a new snapshot during startup if there are changes in the commit log since the last snapshot. If there are no changes, then the existing snapshot will be loaded. Default: `true`
Added in `v1.31` | `boolean` | `false` |
+| `PERSISTENCE_HNSW_DISABLE_SNAPSHOTS` | **Deprecated in `v1.39`.** Ignored, and logs a startup warning. [In `v1.31` through `v1.38`](/weaviate/configuration/hnsw-snapshots.md#pre-v1-39-configuration): if set, HNSW snapshotting will be disabled. Default: `false` (enabled) as of `v1.36`; `true` (disabled) in `v1.31` through `v1.35`
Added in `v1.31` | `boolean` | `false` |
+| `PERSISTENCE_HNSW_SNAPSHOT_INTERVAL_SECONDS` | **Deprecated in `v1.39`.** Ignored, and logs a startup warning. [In `v1.31` through `v1.38`](/weaviate/configuration/hnsw-snapshots.md#pre-v1-39-configuration): the minimum time in seconds that must pass before the next snapshot is created. Default: `21600` seconds (6 hours)
Added in `v1.31` | `string - number` | `3600` |
+| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_NUMBER` | **Deprecated in `v1.39`.** Ignored, and logs a startup warning. [In `v1.31` through `v1.38`](/weaviate/configuration/hnsw-snapshots.md#pre-v1-39-configuration): the minimum number of new commit log files created since the last snapshot. Default: `1`
Added in `v1.31` | `string - number` | `100` |
+| `PERSISTENCE_HNSW_SNAPSHOT_MIN_DELTA_COMMITLOGS_SIZE_PERCENTAGE` | **Deprecated in `v1.39`.** Ignored, and logs a startup warning. [In `v1.31` through `v1.38`](/weaviate/configuration/hnsw-snapshots.md#pre-v1-39-configuration): the minimum total size of new commit logs (as a percentage of the previous snapshot's size) required to trigger a new snapshot. Default: `5` (meaning 5% of the previous snapshot's size in new commit logs)
Added in `v1.31` | `string - number` | `15` |
+| `PERSISTENCE_HNSW_SNAPSHOT_ON_STARTUP` | **Deprecated in `v1.39`.** Ignored, and logs a startup warning. [In `v1.31` through `v1.38`](/weaviate/configuration/hnsw-snapshots.md#pre-v1-39-configuration): if set, Weaviate will try to create a new snapshot during startup if there are changes in the commit log since the last snapshot. If there are no changes, then the existing snapshot will be loaded. Default: `true`
Added in `v1.31` | `boolean` | `false` |
| `PERSISTENCE_HNSW_MAX_LOG_SIZE` | Maximum size of the HNSW [write-ahead-log](/weaviate/concepts/storage.md#hnsw-vector-index-storage). Increase this to improve log compaction efficiency, or decrease to reduce memory requirements. Default: 500MiB | `string` | `4GiB` (IEC units), `4GB` (SI units), `4000000000` (bytes) |
| `PERSISTENCE_LSM_ACCESS_STRATEGY` | Function used to access disk data in virtual memory. Default: `mmap` | `string` | `mmap` or `pread` |
| `PERSISTENCE_LSM_MAX_SEGMENT_SIZE` | Maximum size of a segment in the [LSM store](/weaviate/concepts/storage.md#object-and-inverted-index-store). Set this to limit disk usage spikes during compaction to ~2x the segment size. Default: no limit | `string` | `4GiB` (IEC units), `4GB` (SI units), `4000000000` (bytes) |
diff --git a/docs/weaviate/concepts/storage.md b/docs/weaviate/concepts/storage.md
index f8a4a383..69112ec0 100644
--- a/docs/weaviate/concepts/storage.md
+++ b/docs/weaviate/concepts/storage.md
@@ -101,7 +101,7 @@ For the HNSW vector index, the Write-Ahead-Log (WAL) is a critical component for
The entire HNSW index state can be reconstructed by replaying these WAL entries.
-For very large indexes of tens or hundreds of millions of objects, this can be time-consuming. To avoid replaying the entire WAL on every restart, Weaviate periodically writes **[HNSW snapshots](../configuration/hnsw-snapshots.md)**.
+For very large indexes of tens or hundreds of millions of objects, this can be time-consuming. To avoid replaying the entire WAL on every restart, Weaviate writes **[HNSW snapshots](../configuration/hnsw-snapshots.md)**.
### HNSW snapshots
@@ -111,20 +111,24 @@ import HnswSnapshots from '/_includes/feature-notes/hnsw-snapshots.mdx';
For very large HNSW vector indexes, HNSW snapshots significantly reduce the startup time.
-A snapshot represents a point-in-time state of the HNSW index. When Weaviate starts, if a snapshot exists, it is loaded first, and only the changes made after the snapshot was taken are replayed from the WAL. This significantly reduces startup time, because the number of WAL entries that have to be processed no longer grows with the age of the index.
+A snapshot represents a point-in-time state of the HNSW index. When Weaviate starts, it loads the most recent snapshot and replays only the commit log entries written after it. This significantly reduces startup time, because the number of entries that have to be replayed no longer grows with the age of the index.
-The WAL is still used to persist every change immediately, guaranteeing that any acknowledged write is durable. Even with a fresh snapshot, the server typically still has to load at least one subsequent commit log file.
+The commit log still persists every change immediately, guaranteeing that any acknowledged write is durable. Even with a fresh snapshot, the server typically still has to load at least one subsequent commit log file.
-Starting in `v1.39`, snapshots are part of how the vector index is stored rather than an optional speedup, and Weaviate manages them automatically. A background compactor owns the on-disk lifecycle of the index: it converts each newly flushed commit log into a sorted file, merges sorted files together, and writes a new snapshot when doing so is worthwhile. Snapshot and commit log files live in the same directory, and a snapshot replaces the files it covers rather than duplicating them, which keeps the disk footprint proportional to the size of the index.
+Starting in `v1.39`, snapshots are part of how the vector index is stored rather than an optional speedup, and Weaviate manages them automatically. A background compactor owns the on-disk lifecycle of the index: it compacts newly flushed commit logs, merges them together, and writes a new snapshot when doing so is worthwhile. Snapshots and commit logs live in the same directory, and a snapshot replaces the commit logs it covers rather than duplicating them, which keeps the disk footprint proportional to the size of the index.
Because the merge reads its inputs as sorted streams from disk, only the most recently flushed commit log is processed in memory. That step has a fixed cost regardless of how large the graph is, so snapshot creation no longer requires enough memory to hold the previous snapshot plus the commit log delta.
-Weaviate protects this on-disk state in several ways. New files are written to a temporary path and atomically renamed into place, so an interrupted write can never be mistaken for a complete file, and orphaned temporary files are cleaned up on the next startup. Snapshots are stored in a checksummed block format. If a file cannot be read in full, whether it is a commit log with a torn tail after a crash or a compacted segment damaged on disk, it is truncated back to its last valid entry. The entries written before the damage are retained, and the file becomes valid again so that later compaction can read it. Only the damaged tail is lost, and it is unrecoverable in any case.
+Weaviate protects this on-disk state in several ways. New files are written to a temporary path and atomically renamed into place, so an interrupted write can never be mistaken for a complete file, and orphaned temporary files are cleaned up on the next startup.
+
+Commit logs, including compacted ones, are self-healing. If one cannot be read in full, whether because a crash tore its tail or because the file was damaged on disk, it is truncated back to its last valid entry. The entries written before the damage are retained and the file becomes valid again for later compaction, so only the damaged tail is lost.
+
+Snapshots are handled differently. A snapshot is stored in a checksummed block format, and it is never truncated or repaired. If the current snapshot cannot be read, the affected vector index fails to start rather than loading partial data. Because the commit logs a snapshot covers are deleted once it has been written, nothing remains on the node to replay in its place, so recovering that shard means restoring the data, for example from a [backup](/deploy/configuration/backups.md).
See **[the HNSW snapshots configuration](../configuration/hnsw-snapshots.md)** for version-specific details.
-:::note Behavior before `v1.39`
-In `v1.31` through `v1.38`, snapshots are an optional feature layered on top of the commit log, and are configured with the `PERSISTENCE_HNSW_SNAPSHOT_*` environment variables. They are enabled by default starting in `v1.36`, and disabled by default in `v1.31` through `v1.35`. In these versions, Weaviate creates a snapshot at startup if the commit log changed since the last snapshot, and periodically once a configured time interval has passed and enough new commit log data has accumulated. If a snapshot cannot be loaded, it is removed and Weaviate falls back to loading the full commit log from the beginning. In `v1.39` and later, a snapshot that cannot be read is a startup error instead, because the commit logs it covers no longer exist as a separate copy.
+:::note Behavior in `v1.31` through `v1.38`
+In these versions, snapshots are an optional feature layered on top of the commit log, and are configured with the `PERSISTENCE_HNSW_SNAPSHOT_*` environment variables. They are enabled by default starting in `v1.36`, and disabled by default in `v1.31` through `v1.35`. Weaviate creates a snapshot at startup if the commit log changed since the last snapshot, and periodically once a configured time interval has passed and enough new commit log data has accumulated. If a snapshot cannot be loaded, it is removed and Weaviate falls back to loading the full commit log from the beginning.
:::
## Conclusions
diff --git a/docs/weaviate/configuration/hnsw-snapshots.md b/docs/weaviate/configuration/hnsw-snapshots.md
index 85479f8d..ec0f392f 100644
--- a/docs/weaviate/configuration/hnsw-snapshots.md
+++ b/docs/weaviate/configuration/hnsw-snapshots.md
@@ -21,6 +21,10 @@ Starting in `v1.39`, HNSW snapshots are always enabled and are not configurable.
The commit log compactor owns the on-disk lifecycle of the vector index, and snapshots are one of the file formats it produces. Weaviate creates and maintains them automatically, so there is nothing to enable, disable, schedule, or tune.
+:::caution Snapshots are now required to start
+Because a snapshot replaces the commit logs it covers, it is the only copy of the index state up to that point. If the current snapshot cannot be read, the affected vector index fails to start rather than loading partial data, and it cannot be rebuilt from the node's remaining files. Recovering that shard means restoring the data, for example from a [backup](/deploy/configuration/backups.md). In `v1.31` through `v1.38`, an unreadable snapshot is discarded and Weaviate replays the full commit log instead.
+:::
+
### Environment variables that no longer have an effect
The following environment variables are still recognized, so existing deployments continue to start without a configuration error. However, they are ignored:
@@ -33,12 +37,12 @@ The following environment variables are still recognized, so existing deployment
If any of these variables is set, Weaviate logs a warning at startup that names the variable and states that it has no effect and will be removed in a future version. Variables that are not set produce no warning. To clear the warnings, remove the variables from your deployment configuration.
-Setting the equivalent options in a YAML or JSON configuration file is also accepted and also ignored, but it does not produce a startup warning.
+The same settings in a Weaviate configuration file (`weaviate.conf.json` by default) are accepted and ignored too, but they produce no startup warning.
-## Configuring snapshot creation in versions before `v1.39`
+## Configuring snapshot creation in versions before `v1.39` {#pre-v1-39-configuration}
-:::note
-This section applies to `v1.31` through `v1.38` only. In `v1.39` and later, the environment variables below are ignored.
+:::note Applies to `v1.31` through `v1.38`
+In `v1.39` and later, the environment variables below are ignored.
:::
In these versions, HNSW snapshotting is an optional feature layered on top of the commit log, and the following environment variables control it.
From 903ec899926d795eba12cc8c09cb4f5506d2233d Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:20:33 +0200
Subject: [PATCH 06/12] docs(release-notes): fill the TypeScript client cell
for the v1.38 row
The 1.38.x compatibility row carried literal "-" placeholders for
TypeScript, Go and C#. TypeScript v3.14.0 (published to npm on
2026-07-17) is the first released client with v1.38 support: its CI
matrix adds WEAVIATE_138 (1.38.2), it ships the Boost query parameter,
and it handles the per-collection asyncEnabled setting that v1.38
removed. Go and C# keep their placeholders: the newest published
releases (go-client v5.7.3, Weaviate.Client 1.1.1) still target v1.37,
and only unreleased main-branch work adds v1.38 support.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
_includes/release-history.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/_includes/release-history.md b/_includes/release-history.md
index d0443dab..c830af81 100644
--- a/_includes/release-history.md
+++ b/_includes/release-history.md
@@ -2,7 +2,7 @@ This table lists recent Weaviate Database versions and corresponding client libr
| Weaviate Database
([GitHub][cWeaviate]) | First
release date | Python
([GitHub][cPython]) | TypeScript/
JavaScript
([GitHub][cTypeScript]) | Go
([GitHub][cGo]) | Java
([GitHub][cJava]) | C#
([GitHub][cCSharp]) |
| :------------------------------------------------------------------ | :---------------------- | :-------------------------------------------------------------------------------: | :--------------------------------------------------------------------------: | :-------------------------------------------------------------------------: | :-----------------------------------------------------------------: | :-----------------------------------------------------------------------------: |
-| [1.38.x](https://github.com/weaviate/weaviate/releases/tag/v1.38.0) | 2026-06-05 | [4.22.x](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.22.0) | - | - | [6.3.0](https://github.com/weaviate/java-client/releases/tag/6.3.0) | - |
+| [1.38.x](https://github.com/weaviate/weaviate/releases/tag/v1.38.0) | 2026-06-05 | [4.22.x](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.22.0) | [3.14.x](https://github.com/weaviate/typescript-client/releases/tag/v3.14.0) | - | [6.3.0](https://github.com/weaviate/java-client/releases/tag/6.3.0) | - |
| [1.37.x](https://github.com/weaviate/weaviate/releases/tag/v1.37.0) | 2026-04-16 | [4.21.x](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.21.0) | [3.13.x](https://github.com/weaviate/typescript-client/releases/tag/v3.13.0) | [5.7.3](https://github.com/weaviate/weaviate-go-client/releases/tag/v5.7.3) | [6.2.0](https://github.com/weaviate/java-client/releases/tag/6.2.0) | N/A |
| [1.36.x](https://github.com/weaviate/weaviate/releases/tag/v1.36.0) | 2026-02-24 | [4.20.x](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.20.0) | [3.12.x](https://github.com/weaviate/typescript-client/releases/tag/v3.12.0) | [5.7.x](https://github.com/weaviate/weaviate-go-client/releases/tag/v5.7.0) | [6.1.0](https://github.com/weaviate/java-client/releases/tag/6.1.0) | [1.0.1](https://github.com/weaviate/weaviate-dotnet-client/releases/tag/v1.0.1) |
| [1.35.x](https://github.com/weaviate/weaviate/releases/tag/v1.35.0) | 2025-12-17 | [4.19.x](https://github.com/weaviate/weaviate-python-client/releases/tag/v4.19.0) | [3.11.x](https://github.com/weaviate/typescript-client/releases/tag/v3.11.0) | [5.6.x](https://github.com/weaviate/weaviate-go-client/releases/tag/v5.6.0) | [6.0.0](https://github.com/weaviate/java-client/releases/tag/6.0.0) | [1.0.0](https://github.com/weaviate/weaviate-dotnet-client/releases/tag/v1.0.0) |
From f1ff2ae7be65a223019ed0a062534aa2290694c2 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:35:06 +0200
Subject: [PATCH 07/12] docs(api): document the gRPC-web interface on the REST
port
Weaviate serves gRPC-web under the /v1/grpc-web/ path prefix on the
existing REST port, so browsers can reach the gRPC API without a second
listener. Enabled by default; toggled at runtime with grpc_web_enabled.
No client library speaks gRPC-web yet, so this states that the interface
exists without implying a supported client path or a runnable example.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
docs/weaviate/api/grpc.md | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md
index 4decc0bd..95d5ac35 100644
--- a/docs/weaviate/api/grpc.md
+++ b/docs/weaviate/api/grpc.md
@@ -46,6 +46,17 @@ services:
# ... Other settings
````
+### gRPC-web
+
+:::info Added in `v1.38.3`
+:::
+
+Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
+
+The gRPC-web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override, which takes effect without a restart. While it is disabled, requests under `/v1/grpc-web/` fall through to the REST handler, so the rest of the REST API keeps working as usual.
+
+No Weaviate client library uses this interface yet.
+
### Client-side
You can use the gRPC interface through the [Python (`v4` version)](../client-libraries/python/index.mdx) and [TypeScript (`v3` version)](../client-libraries/typescript/index.mdx) client libraries. Other client libraries will also introduce gRPC support in the near future.
From 88ad31d5e78fe14619a3ebdae4864ef4c1c8b8d9 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:38:58 +0200
Subject: [PATCH 08/12] docs(cloud): note that gRPC-web uses the REST endpoint
URL
In Weaviate Cloud the gRPC-web interface is reached through the REST
Endpoint URL rather than the gRPC Endpoint URL, because it is served on
the REST port.
Added to the existing "REST Endpoint vs gRPC Endpoint" admonition on the
connect page, which already owns this distinction. The default cluster
settings page was considered and rejected: it is a table of setting
defaults with no endpoint content.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
docs/cloud/manage-clusters/connect.mdx | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/cloud/manage-clusters/connect.mdx b/docs/cloud/manage-clusters/connect.mdx
index 3af28250..955f7f77 100644
--- a/docs/cloud/manage-clusters/connect.mdx
+++ b/docs/cloud/manage-clusters/connect.mdx
@@ -80,6 +80,8 @@ If you don't have an existing API key, you'll need to create one. Follow these s
:::note REST Endpoint vs gRPC Endpoint
When using an official Weaviate [client library](/weaviate/client-libraries), you need to authenticate using the `REST Endpoint` and your API key. The client will infer the gRPC endpoint automatically and use the more performant gRPC protocol when available.
+
+The [gRPC-web interface](/weaviate/api/grpc.md#grpc-web) is reached through the `REST Endpoint` URL, not the `gRPC Endpoint` URL, because it is served on the REST port.
:::
### Environment variables
From 645188719c6eea81221ca4c368a3fbe782be763b Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:39:19 +0200
Subject: [PATCH 09/12] docs(config): list grpc_web_enabled as a
runtime-config-only override
grpc_web_enabled has no environment variable. Core only ever seeds it
with a default DynamicValue and has no os.LookupEnv branch, unlike
DEBUG_ENDPOINTS_ENABLED, so it can be set only as a runtime override.
- Add the override to the General table with the environment variable
column marked "not applicable" rather than left blank or invented.
- Soften the page's blanket claim that every runtime configuration
corresponds to an existing environment variable.
- State on the gRPC API page that there is no environment variable
equivalent, so readers who know the convention stop looking.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
docs/deploy/configuration/env-vars/runtime-config.md | 5 ++++-
docs/weaviate/api/grpc.md | 2 +-
2 files changed, 5 insertions(+), 2 deletions(-)
diff --git a/docs/deploy/configuration/env-vars/runtime-config.md b/docs/deploy/configuration/env-vars/runtime-config.md
index 137ead48..1653add5 100644
--- a/docs/deploy/configuration/env-vars/runtime-config.md
+++ b/docs/deploy/configuration/env-vars/runtime-config.md
@@ -11,7 +11,7 @@ import RuntimeConfig from '/_includes/feature-notes/runtime-config.mdx';
Weaviate supports runtime configuration management, allowing some configurations to be changed without any further restarts.
-Each runtime configuration corresponds to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable.
+Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable. A few settings are available only as runtime overrides and have no environment variable equivalent.
## How to set up runtime configuration
@@ -69,6 +69,7 @@ The following overrides are currently supported:
| `export_default_path` | `EXPORT_DEFAULT_PATH` |
| `export_enabled` | `EXPORT_ENABLED` |
| `export_parallelism` | `EXPORT_PARALLELISM` |
+| `grpc_web_enabled` | _(not applicable)_ |
| `inverted_sorter_disabled` | `INVERTED_SORTER_DISABLED` |
| `maximum_allowed_collections_count` | `MAXIMUM_ALLOWED_COLLECTIONS_COUNT` |
| `objects_ttl_batch_size` | `OBJECTS_TTL_BATCH_SIZE` |
@@ -85,6 +86,8 @@ The following overrides are currently supported:
| `tenant_activity_read_log_level` | `TENANT_ACTIVITY_READ_LOG_LEVEL` |
| `tenant_activity_write_log_level` | `TENANT_ACTIVITY_WRITE_LOG_LEVEL` |
+`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent, so it can only be set as a runtime override.
+
### Raft settings
| Runtime override name | Environment variable name |
diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md
index 95d5ac35..2e34f66c 100644
--- a/docs/weaviate/api/grpc.md
+++ b/docs/weaviate/api/grpc.md
@@ -53,7 +53,7 @@ services:
Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
-The gRPC-web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override, which takes effect without a restart. While it is disabled, requests under `/v1/grpc-web/` fall through to the REST handler, so the rest of the REST API keeps working as usual.
+The gRPC-web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override, which takes effect without a restart. There is no environment variable equivalent. While it is disabled, requests under `/v1/grpc-web/` fall through to the REST handler, so the rest of the REST API keeps working as usual.
No Weaviate client library uses this interface yet.
From 07d3dfbe1c58b818d2c92401d52a1f11fffbfe30 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 13:48:16 +0200
Subject: [PATCH 10/12] docs: apply editor review to the gRPC-Web mentions
- Use the protocol's own capitalisation, gRPC-Web, in prose. Code-font
/v1/grpc-web/, grpc_web_enabled and the #grpc-web anchor are unchanged,
so cross-links still resolve.
- Say to set the override to false rather than leaving the value implied.
- Promote the section to a "## gRPC-Web" sibling so the matched
Server-side / Client-side pair is no longer split.
- Give the no-environment-variable sentence a subject and attach it to
the enablement idea.
- Drop the rest/REST collision and the vague antecedent.
- Tie the client-library guard to the browser framing so it cannot be
misread as contradicting client gRPC support.
- Make the cloud sentence second person, matching its admonition.
- Avoid a third term for the same concept on the runtime-config page.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
docs/cloud/manage-clusters/connect.mdx | 2 +-
.../configuration/env-vars/runtime-config.md | 4 ++--
docs/weaviate/api/grpc.md | 22 +++++++++----------
3 files changed, 14 insertions(+), 14 deletions(-)
diff --git a/docs/cloud/manage-clusters/connect.mdx b/docs/cloud/manage-clusters/connect.mdx
index 955f7f77..4e0a7d73 100644
--- a/docs/cloud/manage-clusters/connect.mdx
+++ b/docs/cloud/manage-clusters/connect.mdx
@@ -81,7 +81,7 @@ If you don't have an existing API key, you'll need to create one. Follow these s
:::note REST Endpoint vs gRPC Endpoint
When using an official Weaviate [client library](/weaviate/client-libraries), you need to authenticate using the `REST Endpoint` and your API key. The client will infer the gRPC endpoint automatically and use the more performant gRPC protocol when available.
-The [gRPC-web interface](/weaviate/api/grpc.md#grpc-web) is reached through the `REST Endpoint` URL, not the `gRPC Endpoint` URL, because it is served on the REST port.
+To reach the [gRPC-Web interface](/weaviate/api/grpc.md#grpc-web), use the `REST Endpoint` URL, not the `gRPC Endpoint` URL, because gRPC-Web is served on the REST port.
:::
### Environment variables
diff --git a/docs/deploy/configuration/env-vars/runtime-config.md b/docs/deploy/configuration/env-vars/runtime-config.md
index 1653add5..08ae7230 100644
--- a/docs/deploy/configuration/env-vars/runtime-config.md
+++ b/docs/deploy/configuration/env-vars/runtime-config.md
@@ -11,7 +11,7 @@ import RuntimeConfig from '/_includes/feature-notes/runtime-config.mdx';
Weaviate supports runtime configuration management, allowing some configurations to be changed without any further restarts.
-Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable. A few settings are available only as runtime overrides and have no environment variable equivalent.
+Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable. A few runtime configurations are available only as overrides and have no environment variable equivalent.
## How to set up runtime configuration
@@ -86,7 +86,7 @@ The following overrides are currently supported:
| `tenant_activity_read_log_level` | `TENANT_ACTIVITY_READ_LOG_LEVEL` |
| `tenant_activity_write_log_level` | `TENANT_ACTIVITY_WRITE_LOG_LEVEL` |
-`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent, so it can only be set as a runtime override.
+`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-Web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent, so it can only be set as a runtime override.
### Raft settings
diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md
index 2e34f66c..23e7e135 100644
--- a/docs/weaviate/api/grpc.md
+++ b/docs/weaviate/api/grpc.md
@@ -46,17 +46,6 @@ services:
# ... Other settings
````
-### gRPC-web
-
-:::info Added in `v1.38.3`
-:::
-
-Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
-
-The gRPC-web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override, which takes effect without a restart. There is no environment variable equivalent. While it is disabled, requests under `/v1/grpc-web/` fall through to the REST handler, so the rest of the REST API keeps working as usual.
-
-No Weaviate client library uses this interface yet.
-
### Client-side
You can use the gRPC interface through the [Python (`v4` version)](../client-libraries/python/index.mdx) and [TypeScript (`v3` version)](../client-libraries/typescript/index.mdx) client libraries. Other client libraries will also introduce gRPC support in the near future.
@@ -66,6 +55,17 @@ Alternatively, you can use other tools, such as the `grpcurl` command-line tool,
- `grpcurl` command-line tool ([GitHub repo](https://github.com/fullstorydev/grpcurl))
- Postman ([How to send a gRPC request with Postman](https://learning.postman.com/docs/sending-requests/grpc/grpc-request-interface/))
+## gRPC-Web
+
+:::info Added in `v1.38.3`
+:::
+
+Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-Web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
+
+The gRPC-Web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override to `false`, which takes effect without a restart. This setting has no environment variable equivalent. When the interface is disabled, requests to `/v1/grpc-web/` fall through to the REST handler, so other REST endpoints keep working as usual.
+
+The Weaviate client libraries connect over plain gRPC, so they do not use the gRPC-Web interface yet.
+
## Questions and feedback
import DocsFeedback from "/\_includes/docs-feedback.mdx";
From 8090da971c9054e8606b84cad061b04e09ae1b9b Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 15:30:25 +0200
Subject: [PATCH 11/12] docs: cover both gRPC-Web toggle surfaces and their
casing split
The interface can be turned off in two places, and core spells the key
differently in each: grpc.grpcWebEnabled in the static configuration
file, grpc_web_enabled as a runtime override. Present them as a short
list so the camelCase/snake_case split cannot be skimmed past.
Also correct the runtime-config note, which claimed the setting could
only be set as a runtime override. That is now false. The separate
"no environment variable equivalent" statement stands: a configuration
file field is not an environment variable.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01THnwHPggu8hcxb2BTMLLRB
---
docs/deploy/configuration/env-vars/runtime-config.md | 2 +-
docs/weaviate/api/grpc.md | 7 ++++++-
2 files changed, 7 insertions(+), 2 deletions(-)
diff --git a/docs/deploy/configuration/env-vars/runtime-config.md b/docs/deploy/configuration/env-vars/runtime-config.md
index 08ae7230..b74253cc 100644
--- a/docs/deploy/configuration/env-vars/runtime-config.md
+++ b/docs/deploy/configuration/env-vars/runtime-config.md
@@ -86,7 +86,7 @@ The following overrides are currently supported:
| `tenant_activity_read_log_level` | `TENANT_ACTIVITY_READ_LOG_LEVEL` |
| `tenant_activity_write_log_level` | `TENANT_ACTIVITY_WRITE_LOG_LEVEL` |
-`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-Web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent, so it can only be set as a runtime override.
+`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-Web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent. In the static configuration file the same setting is spelled `grpc.grpcWebEnabled`, in camelCase.
### Raft settings
diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md
index 23e7e135..855c12a3 100644
--- a/docs/weaviate/api/grpc.md
+++ b/docs/weaviate/api/grpc.md
@@ -62,7 +62,12 @@ Alternatively, you can use other tools, such as the `grpcurl` command-line tool,
Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-Web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
-The gRPC-Web interface is enabled by default. To turn it off, set the `grpc_web_enabled` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override to `false`, which takes effect without a restart. This setting has no environment variable equivalent. When the interface is disabled, requests to `/v1/grpc-web/` fall through to the REST handler, so other REST endpoints keep working as usual.
+The gRPC-Web interface is enabled by default. It can be turned off in two places, and the key is spelled differently in each:
+
+- **Static configuration file:** set `grpc.grpcWebEnabled` to `false`. Note the camelCase.
+- **[Runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override:** set `grpc_web_enabled` to `false`. Note the snake_case. This takes effect without a restart.
+
+This setting has no environment variable equivalent. When the interface is disabled, requests to `/v1/grpc-web/` fall through to the REST handler, so other REST endpoints keep working as usual.
The Weaviate client libraries connect over plain gRPC, so they do not use the gRPC-Web interface yet.
From 725373f762ef644b70b1ea5ebfb441e8c0560297 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 4 Aug 2026 15:48:49 +0200
Subject: [PATCH 12/12] Update descriptions
---
docs/deploy/configuration/env-vars/runtime-config.md | 4 +---
docs/weaviate/api/grpc.md | 5 +----
2 files changed, 2 insertions(+), 7 deletions(-)
diff --git a/docs/deploy/configuration/env-vars/runtime-config.md b/docs/deploy/configuration/env-vars/runtime-config.md
index b74253cc..f59609fd 100644
--- a/docs/deploy/configuration/env-vars/runtime-config.md
+++ b/docs/deploy/configuration/env-vars/runtime-config.md
@@ -11,7 +11,7 @@ import RuntimeConfig from '/_includes/feature-notes/runtime-config.mdx';
Weaviate supports runtime configuration management, allowing some configurations to be changed without any further restarts.
-Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable. A few runtime configurations are available only as overrides and have no environment variable equivalent.
+Most runtime configurations correspond to an existing environment variable. When a runtime configuration is updated, it overrides the value set by the corresponding environment variable.
## How to set up runtime configuration
@@ -86,8 +86,6 @@ The following overrides are currently supported:
| `tenant_activity_read_log_level` | `TENANT_ACTIVITY_READ_LOG_LEVEL` |
| `tenant_activity_write_log_level` | `TENANT_ACTIVITY_WRITE_LOG_LEVEL` |
-`grpc_web_enabled` (added in `v1.38.3`) controls the [gRPC-Web interface](/weaviate/api/grpc.md#grpc-web) and has no environment variable equivalent. In the static configuration file the same setting is spelled `grpc.grpcWebEnabled`, in camelCase.
-
### Raft settings
| Runtime override name | Environment variable name |
diff --git a/docs/weaviate/api/grpc.md b/docs/weaviate/api/grpc.md
index 855c12a3..ee400aec 100644
--- a/docs/weaviate/api/grpc.md
+++ b/docs/weaviate/api/grpc.md
@@ -62,10 +62,7 @@ Alternatively, you can use other tools, such as the `grpcurl` command-line tool,
Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-Web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.
-The gRPC-Web interface is enabled by default. It can be turned off in two places, and the key is spelled differently in each:
-
-- **Static configuration file:** set `grpc.grpcWebEnabled` to `false`. Note the camelCase.
-- **[Runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override:** set `grpc_web_enabled` to `false`. Note the snake_case. This takes effect without a restart.
+The gRPC-Web interface is enabled by default. **[Runtime configuration](/deploy/configuration/env-vars/runtime-config.md) override:** set `grpc_web_enabled` to `false`. Note the snake_case. This takes effect without a restart.
This setting has no environment variable equivalent. When the interface is disabled, requests to `/v1/grpc-web/` fall through to the REST handler, so other REST endpoints keep working as usual.