From 872506c0e01afd7e24d45ee6d3731a730b8b7562 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Fri, 22 Aug 2025 07:14:07 +0200
Subject: [PATCH 01/44] Prepare release branch
---
versions-config.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/versions-config.json b/versions-config.json
index f46e30f5..3dae6a84 100644
--- a/versions-config.json
+++ b/versions-config.json
@@ -1,7 +1,7 @@
{
"COMMENT1": "These values are used for yarn local yarn builds",
"COMMENT2": "Build time values are set in _build_scripts/update-config-versions.js",
- "weaviate_version": "1.32.1",
+ "weaviate_version": "1.33.0",
"helm_version": "17.3.3",
"weaviate_cli_version": "3.2.2",
"weaviate_agents_version": "0.12.0",
From ccc5e0b888272a1ad9e097f462cb61d5bd4ec263 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Fri, 22 Aug 2025 07:32:41 +0200
Subject: [PATCH 02/44] Add 1-bit RQ changes
---
.../rq-compression-parameters.mdx | 8 ++--
docs/weaviate/concepts/vector-quantization.md | 43 ++++++++++++++++---
.../compression/rq-compression.md | 5 ++-
3 files changed, 44 insertions(+), 12 deletions(-)
diff --git a/_includes/configuration/rq-compression-parameters.mdx b/_includes/configuration/rq-compression-parameters.mdx
index 0e33fba6..7bee774c 100644
--- a/_includes/configuration/rq-compression-parameters.mdx
+++ b/_includes/configuration/rq-compression-parameters.mdx
@@ -1,4 +1,4 @@
-| Parameter | Type | Default | Details |
-| :------------------- | :------ | :------ | :--------------------------------------------------------------------------------------- |
-| `rq`: `bits` | integer | 8 | The number of bits used to quantize each data point. Currently only 8 bits is supported. |
-| `rq`: `rescoreLimit` | integer | -1 | The minimum number of candidates to fetch before rescoring. |
+| Parameter | Type | Default | Details |
+| :------------------- | :------ | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rq`: `bits` | integer | `8` | The number of bits used to quantize each data point. Can be `8` or `1`. Learn more about [8-bit](/weaviate/concepts/vector-quantization#8-bit-rq) and [1-bit](/weaviate/concepts/vector-quantization#1-bit-rq) RQ. |
+| `rq`: `rescoreLimit` | integer | `-1` | The minimum number of candidates to fetch before rescoring. |
diff --git a/docs/weaviate/concepts/vector-quantization.md b/docs/weaviate/concepts/vector-quantization.md
index 3945e487..439cd945 100644
--- a/docs/weaviate/concepts/vector-quantization.md
+++ b/docs/weaviate/concepts/vector-quantization.md
@@ -29,7 +29,7 @@ Vector quantization is a technique that reduces the memory footprint of vector e
PQ reduces the size of each vector embedding in two steps. First, it reduces the number of vector dimensions to a smaller number of "segments", and then each segment is quantized to a smaller number of bits from the original number of bits (typically a 32-bit float).
-import PQTradeoffs from '/_includes/configuration/pq-compression/tradeoffs.mdx' ;
+import PQTradeoffs from '/\_includes/configuration/pq-compression/tradeoffs.mdx' ;
@@ -50,7 +50,7 @@ The PQ `segments` controls the tradeoff between memory and recall. A larger `seg
Below is a list segment values for common vectorizer modules:
| Module | Model | Dimensions | Segments |
-|-------------|-----------------------------------------|------------|------------------------|
+| ----------- | --------------------------------------- | ---------- | ---------------------- |
| openai | text-embedding-ada-002 | 1536 | 512, 384, 256, 192, 96 |
| cohere | multilingual-22-12 | 768 | 384, 256, 192, 96 |
| huggingface | sentence-transformers/all-MiniLM-L12-v2 | 384 | 192, 128, 96 |
@@ -66,9 +66,11 @@ Weaviate uses a maximum of `trainingLimit` objects (per shard) for training, eve
After the PQ conversion completes, query and write to the index as normal. Distances may be slightly different due to the effects of quantization.
:::info Which objects are used for training?
+
- (`v1.27` and later) If the collection has more objects than the training limit, Weaviate randomly selects objects from the collection to train the codebook.
- - (`v1.26` and earlier) Weaviate uses the first `trainingLimit` objects in the collection to train the codebook.
+- (`v1.26` and earlier) Weaviate uses the first `trainingLimit` objects in the collection to train the codebook.
- If the collection has fewer objects than the training limit, Weaviate uses all objects in the collection to train the codebook.
+
:::
### Encoders
@@ -120,20 +122,45 @@ This means that the feature is still under development and may change in future
:::
-**Rotational quantization (RQ)** is an untrained 8-bit quantization technique that provides 4x compression while maintaining 98-99% recall on most datasets. Unlike SQ, RQ requires no training phase and can be enabled immediately at index creation. RQ works in two steps:
+**Rotational quantization (RQ)** is an untrained quantization technique that provides significant compression while maintaining high recall on most datasets. Unlike SQ, RQ requires no training phase and can be enabled immediately at index creation. RQ is available in two variants: **8-bit RQ** and **1-bit RQ**.
+
+### 8-bit RQ
+
+8-bit RQ provides 4x compression while maintaining 98-99% recall on most datasets. RQ works in two steps:
1. **Fast pseudorandom rotation**: The input vector is transformed using a fast rotation based on the Walsh Hadamard Transform. This rotation takes approximately 7-10 microseconds for a 1536-dimensional vector. The output dimension is rounded up to the nearest multiple of 64.
2. **Scalar quantization**: Each entry of the rotated vector is quantized to an 8-bit integer. The minimum and maximum values of each individual rotated vector define the quantization interval.
+### 1-bit RQ
+
+1-bit RQ is an untrained asymmetric quantization method that provides close to 32x compression as dimensionality increases. This method is inspired by 1-bit RaBitQ and works as follows:
+
+1. **Fast pseudorandom rotation**: The same rotation process as 8-bit RQ is applied to the input vector.
+
+2. **Asymmetric quantization**:
+ - **Data vectors**: Quantized using 1 bit per dimension by storing only the sign of each entry
+ - **Query vectors**: Scalar quantized using 5 bits per dimension during search
+
+This asymmetric approach improves recall compared to symmetric 1-bit schemes (such as BQ) by using more precision for query vectors during distance calculation. On datasets well-suited for BQ (like OpenAI embeddings), 1-bit RQ essentially matches BQ recall. It also works well on datasets where BQ performs poorly (such as [SIFT](https://arxiv.org/abs/2504.09081))
+
+### RQ characteristics
+
The rotation step provides multiple benefits. It tends to reduce the quantization interval and decrease quantization error by distributing values more uniformly. It also distributes the distance information more evenly across all dimensions, providing a better starting point for distance estimation.
-It's worth noting that RQ rounds up dimensions to multiples of 64 which means that low-dimensional data (< 64 or 128 dimensions) might result in less than optimal compression.
+It's worth noting that both RQ variants round up dimensions to multiples of 64, which means that low-dimensional data (< 64 or 128 dimensions) might result in less than optimal compression.
+
+While inspired by extended RaBitQ, this implementation differs significantly for performance reasons. It uses fast pseudorandom rotations instead of truly random rotations.
+
+- For 8-bit RQ: employs scalar quantization instead of RaBitQ's encoding algorithm
+- For 1-bit RQ: uses word-level parallelism across dimensions for faster distance estimation
-While inspired by extended RaBitQ, this implementation differs significantly for performance reasons. It Uses fast pseudorandom rotations instead of truly random rotations and it employs scalar quantization instead of RaBitQ's encoding algorithm, which becomes prohibitively slow with more bits per entry.
+From the user perspective, 1-bit RQ is not a separate quantization method, but rather a configuration setting for RQ.
:::tip
+
Learn more about how to [configure rotational quantization](../configuration/compression/rq-compression.md) in Weaviate.
+
:::
## Over-fetching / re-scoring
@@ -173,6 +200,7 @@ In some cases, rescoring also includes over-fetching, whereby additional candida
## Further resources
:::info Related pages
+
- [Concepts: Indexing](./indexing/index.md)
- [Concepts: Vector Indexing](./indexing/vector-index.md)
- [Configuration: Vector index](../config-refs/indexing/vector-index.mdx)
@@ -182,10 +210,11 @@ In some cases, rescoring also includes over-fetching, whereby additional candida
- [How to configure: Scalar quantization (compression)](../configuration/compression/sq-compression.md)
- [How to configure: Rotational quantization (compression)](../configuration/compression/rq-compression.md)
- [Weaviate Academy: 250 Vector Compression](../../academy/py/compression/index.md)
+
:::
## Questions and feedback
-import DocsFeedback from '/_includes/docs-feedback.mdx';
+import DocsFeedback from '/\_includes/docs-feedback.mdx';
diff --git a/docs/weaviate/configuration/compression/rq-compression.md b/docs/weaviate/configuration/compression/rq-compression.md
index fe697bd0..fda60947 100644
--- a/docs/weaviate/configuration/compression/rq-compression.md
+++ b/docs/weaviate/configuration/compression/rq-compression.md
@@ -21,7 +21,10 @@ This means that the feature is still under development and may change in future
:::
-[**Rotational quantization (RQ)**](../../concepts/vector-quantization.md#rotational-quantization) is a fast untrained vector compression technique that offers 4x compression while retaining almost perfect recall (98-99% on most datasets).
+[**Rotational quantization (RQ)**](../../concepts/vector-quantization.md#rotational-quantization) is a fast untrained vector compression technique:
+
+- **8-bit RQ**: Up to 4x compression while retaining almost perfect recall (98-99% on most datasets).
+- **1-bit RQ**: Close to 32x compression as dimensionality increases with moderate recall across various datasets.
:::note HNSW only
RQ is currently not supported for the flat index type.
From 551e7fb8b674c3596edd2c2f3931057e30cebfaa Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Mon, 25 Aug 2025 11:42:45 +0200
Subject: [PATCH 03/44] Add batch import docs
---
_includes/code/howto/manage-data.import.py | 45 ++++
docs/weaviate/concepts/data-import.mdx | 65 ++++++
docs/weaviate/manage-objects/import.mdx | 229 ++++++++++++---------
3 files changed, 246 insertions(+), 93 deletions(-)
create mode 100644 docs/weaviate/concepts/data-import.mdx
diff --git a/_includes/code/howto/manage-data.import.py b/_includes/code/howto/manage-data.import.py
index 349ffa48..ff104e2e 100644
--- a/_includes/code/howto/manage-data.import.py
+++ b/_includes/code/howto/manage-data.import.py
@@ -557,4 +557,49 @@ def add_object(obj) -> None:
# Clean up
client.collections.delete("NewCollection")
+
+# ==================================================
+# ===== Server-side (automatic) batch import =====
+# ==================================================
+
+# Re-create the collection
+client.collections.delete("MyCollection")
+client.collections.create(
+ "MyCollection",
+ vector_config=Configure.Vectors.self_provided()
+)
+
+# START ServerSideBatchImportExample
+data_rows = [
+ {"title": f"Object {i+1}"} for i in range(5)
+]
+
+collection = client.collections.get("MyCollection")
+
+# highlight-start
+# Use `automatic` for server-side batching. The client will send data
+# in chunks and the server will dynamically manage the import process.
+with collection.batch.automatic() as batch:
+ for data_row in data_rows:
+ batch.add_object(
+ properties=data_row,
+ )
+# highlight-end
+ if batch.number_errors > 10:
+ print("Batch import stopped due to excessive errors.")
+ break
+
+failed_objects = collection.batch.failed_objects
+if failed_objects:
+ print(f"Number of failed imports: {len(failed_objects)}")
+ print(f"First failed object: {failed_objects[0]}")
+# END ServerSideBatchImportExample
+
+result = collection.aggregate.over_all(total_count=True)
+assert result.total_count == 5
+
+# Clean up
+client.collections.delete(collection.name)
+
+
client.close()
diff --git a/docs/weaviate/concepts/data-import.mdx b/docs/weaviate/concepts/data-import.mdx
new file mode 100644
index 00000000..43b51296
--- /dev/null
+++ b/docs/weaviate/concepts/data-import.mdx
@@ -0,0 +1,65 @@
+---
+title: Data import
+sidebar_position: 11
+description: "Theoretical explanation of client-side and server-side batch imports."
+image: og/docs/concepts.jpg
+---
+
+Weaviate offers two flexible methods for importing data in bulk: **client-side batching** and **server-side batching**. This allows you to choose the best strategy based on your specific needs for control and simplicity.
+
+### Client-side batching
+
+In the traditional client-side approach, **your application is responsible for grouping data into batches**. You define the exact size of each batch (e.g., 100 objects) using the appropriate [client library method](../manage-objects/import.mdx). The client then sends these pre-defined chunks to the Weaviate server.
+
+This method gives you direct control over the import process but may require manual tuning of parameters like `batch_size` and `concurrent_requests` to achieve optimal performance and avoid overwhelming the server.
+
+### Server-side batching
+
+Server-side batching, or **automatic mode**, is a more robust and the recommended approach. Here, the client sends data as a continuous stream, and the **Weaviate server intelligently manages the data flow**.
+
+Using an internal queue and a dynamic **backpressure** mechanism, the server tells the client how much data to send next based on its current workload. This simplifies your client code, eliminates the need for manual tuning, and results in a more efficient and resilient data import process.
+
+:::tip
+
+For **code examples**, check out the [How-to: Batch import](../manage-objects/import.mdx) guide. Currently, only the Python client supports batch imports.
+
+:::
+
+---
+
+## Server-side batching (Automatic mode)
+
+Weaviate's server-side batching, also known as **automatic batching**, is an intelligent mechanism designed to make data ingestion simpler, faster, and more robust. Instead of manually tuning batch parameters on the client side, you can let the server dynamically manage the data flow for optimal performance.
+
+This mode is a drop-in replacement for `fixed_size` or `dynamic` batching and is the recommended method for importing data.
+
+### How it works
+
+When you use the `automatic()` batching context manager, you initiate a persistent connection to the server for the duration of the batch job.
+
+1. **Client Sends Data**: Your client sends objects to the server in chunks. These requests execute instantly without waiting for the data to be fully imported.
+2. **Server Manages Queues**: The server places incoming objects into an internal queue system. This decouples the network communication from the actual database work (like vectorization and storage).
+3. **Dynamic Backpressure**: The server continuously monitors its internal queue size. It calculates an exponential moving average (EMA) of its workload and tells the client the ideal number of objects to send in the next chunk. This feedback loop allows the system to self-regulate, maximizing throughput without overwhelming the server.
+4. **Asynchronous Errors**: If an error occurs while processing an object (e.g., validation fails), the server sends the error message back to the client over a separate, dedicated stream without interrupting the flow of other objects.
+
+This architecture centralizes the complex batching logic on the server, resulting in a more efficient and stable data ingestion pipeline for all connected clients.
+
+:::info Why use automatic batching?
+
+- **Simplified client code**: No need to tweak `batch_size` and `concurrent_requests` manually. The server determines the optimal batch size based on its current workload.
+- **Improved stability**: The system automatically applies **backpressure**. If the server is busy, it will instruct the client to send less data, preventing overloads and request timeouts, which is especially useful during long-running vectorization tasks.
+- **Enhanced resilience**: It's designed to handle cluster events like node scaling more gracefully, reducing the risk of interrupted batches.
+- **Streamlined error handling**: Errors are streamed back from the server asynchronously. A single failed object won't halt the entire import process, and you can handle errors as they arrive.
+
+:::
+
+## Further resources
+
+- [How-to: Batch import](../manage-objects/import.mdx)
+- [How-to: Create objects](../manage-objects/create.mdx)
+
+## Questions and feedback
+
+import DocsFeedback from "/_includes/docs-feedback.mdx";
+
+
diff --git a/docs/weaviate/manage-objects/import.mdx b/docs/weaviate/manage-objects/import.mdx
index 02ae6110..b0961a76 100644
--- a/docs/weaviate/manage-objects/import.mdx
+++ b/docs/weaviate/manage-objects/import.mdx
@@ -4,18 +4,18 @@ sidebar_position: 15
image: og/docs/howto.jpg
---
-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/manage-data.import.py';
-import PyCodeV3 from '!!raw-loader!/_includes/code/howto/manage-data.import-v3.py';
-import PySuppCode from '!!raw-loader!/_includes/code/howto/sample-data.py';
-import TSCode from '!!raw-loader!/_includes/code/howto/manage-data.import.ts';
-import TSCodeLegacy from '!!raw-loader!/_includes/code/howto/manage-data.import-v2.ts';
-import TsSuppCode from '!!raw-loader!/_includes/code/howto/sample-data.ts';
-import JavaCode from '!!raw-loader!/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.import.java';
-import GoCode from '!!raw-loader!/_includes/code/howto/go/docs/manage-data.import_test.go';
-import SkipLink from '/src/components/SkipValidationLink'
+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/manage-data.import.py";
+import PyCodeV3 from "!!raw-loader!/_includes/code/howto/manage-data.import-v3.py";
+import PySuppCode from "!!raw-loader!/_includes/code/howto/sample-data.py";
+import TSCode from "!!raw-loader!/_includes/code/howto/manage-data.import.ts";
+import TSCodeLegacy from "!!raw-loader!/_includes/code/howto/manage-data.import-v2.ts";
+import TsSuppCode from "!!raw-loader!/_includes/code/howto/sample-data.ts";
+import JavaCode from "!!raw-loader!/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.import.java";
+import GoCode from "!!raw-loader!/_includes/code/howto/go/docs/manage-data.import_test.go";
+import SkipLink from "/src/components/SkipValidationLink";
[Batch imports](../tutorials/import.md#to-batch-or-not-to-batch) are an efficient way to add multiple data objects and cross-references.
@@ -46,6 +46,7 @@ The following example adds objects to the `MyCollection` collection.
### Error handling
+
During a batch import, any failed objects or references will be stored and can be obtained through `batch.failed_objects` and `batch.failed_references`.
Additionally, a running count of failed objects and references is maintained and can be accessed through `batch.number_errors` within the context manager.
This counter can be used to stop the import process in order to investigate the failed objects or references.
@@ -53,7 +54,6 @@ This counter can be used to stop the import process in order to investigate the
Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python).
-
-
-
-
-
+## Server-side batching
+
+:::caution Technical preview
+
+Server-side batching was added in **`v1.33`** as a **technical preview**.
+This means that the feature is still under development and may change in future releases, including potential breaking changes.
+**We do not recommend using this feature in production environments at this time.**
+
+:::
+
+Here's how to import objects into a collection named `MyCollection`. The client will handle sending the data in optimal chunks.
+
+
+
+
+
+### Error handling
+
+
+
+During a batch import, any failed objects or references will be stored and can be obtained through `batch.failed_objects` and `batch.failed_references`.
+Additionally, a running count of failed objects and references is maintained and can be accessed through `batch.number_errors` within the context manager.
+This counter can be used to stop the import process in order to investigate the failed objects or references.
+
+Find out more about error handling on the Python client [reference page](/weaviate/client-libraries/python).
+
+
+
+
+```typescript
+// TypeScript support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
## Use the gRPC API
:::info Added in `v1.23`.
@@ -108,20 +159,23 @@ Find out more about error handling on the Python client [reference page](/weavia
The [gRPC API](../api/index.mdx) is faster than the REST API. Use the gRPC API to improve import speeds.
-
+
-The Python client uses gRPC by default.
- The legacy Python client does not support gRPC.
+The Python client uses gRPC by default.
+
+
+The legacy Python client does not support gRPC.
The TypeScript client v3 uses gRPC by default.
- The legacy TypeScript client does not support gRPC.
+
+The legacy TypeScript client does not support gRPC.
@@ -133,6 +187,7 @@ Config config = new Config("http", "localhost:8080");
config.setGRPCSecured(false);
config.setGRPCHost("localhost:50051");
```
+
@@ -155,6 +210,7 @@ if err != nil {
require.Nil(t, err)
}
```
+
@@ -193,7 +249,6 @@ Weaviate generates an UUID for each object. Object IDs must be unique. If you se
language="py"
/>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
## Import with references
@@ -382,6 +424,7 @@ You can batch create links from an object to another other object through cross-
The Python clients have built-in batching methods to help you optimize import speed. For details, see the client documentation:
+
- [Python client `v4`](../client-libraries/python/index.mdx)
### Async Python client and batching
@@ -399,20 +442,20 @@ To try the example code, download the sample data and create the sample input fi
-
+
-
+
@@ -423,61 +466,60 @@ To try the example code, download the sample data and create the sample input fi
-
+
-
+
-
+
-
Stream CSV files example code
-
+
-
+
-
+
@@ -488,7 +530,7 @@ To try the example code, download the sample data and create the sample input fi
:::info Added in `v1.25`.
:::
-import BatchVectorizationOverview from '/_includes/code/client-libraries/batch-import.mdx';
+import BatchVectorizationOverview from "/_includes/code/client-libraries/batch-import.mdx";
@@ -498,7 +540,7 @@ You can configure the batch vectorization settings for each model provider, such
Note that each provider exposes different configuration options.
-
+
+
For details, see [auto-tenant](/weaviate/manage-collections/multi-tenancy#automatically-add-new-tenants).
-
-## Related pages
+## Further resources
- [Connect to Weaviate](/weaviate/connections/index.mdx)
- [How-to: Create objects](./create.mdx)
-- References: REST - /v1/batch
+-
+ References: REST - /v1/batch
+
- [Configuration: Indexes](/weaviate/config-refs/indexing/vector-index.mdx#asynchronous-indexing)
## Questions and feedback
-import DocsFeedback from '/_includes/docs-feedback.mdx';
+import DocsFeedback from "/_includes/docs-feedback.mdx";
-
+
From 7d35fc5015535a141c1c3d3139b90e545d3370f1 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Mon, 25 Aug 2025 12:34:18 +0200
Subject: [PATCH 04/44] Update docs
---
docs/weaviate/concepts/data-import.mdx | 28 ++++++++++++--------------
1 file changed, 13 insertions(+), 15 deletions(-)
diff --git a/docs/weaviate/concepts/data-import.mdx b/docs/weaviate/concepts/data-import.mdx
index 43b51296..48e19a47 100644
--- a/docs/weaviate/concepts/data-import.mdx
+++ b/docs/weaviate/concepts/data-import.mdx
@@ -5,19 +5,17 @@ description: "Theoretical explanation of client-side and server-side batch impor
image: og/docs/concepts.jpg
---
-Weaviate offers two flexible methods for importing data in bulk: **client-side batching** and **server-side batching**. This allows you to choose the best strategy based on your specific needs for control and simplicity.
+Weaviate offers two flexible methods for importing data in bulk: **client-side batching** and **server-side batching**. This allows you to choose the best strategy based on your specific needs.
-### Client-side batching
+- **Client-side batching**
+ In the traditional client-side approach, **your application is responsible for grouping data into batches**. You define the exact size of each batch (e.g., 100 objects) using the appropriate [client library method](../manage-objects/import.mdx). The client then sends these pre-defined chunks to the Weaviate server.
-In the traditional client-side approach, **your application is responsible for grouping data into batches**. You define the exact size of each batch (e.g., 100 objects) using the appropriate [client library method](../manage-objects/import.mdx). The client then sends these pre-defined chunks to the Weaviate server.
+ This method gives you direct control over the import process but may require manual tuning of parameters like `batch_size` and `concurrent_requests` to achieve optimal performance and avoid overwhelming the server.
-This method gives you direct control over the import process but may require manual tuning of parameters like `batch_size` and `concurrent_requests` to achieve optimal performance and avoid overwhelming the server.
+- **Server-side batching**
+ Server-side batching, or **automatic mode**, is a more robust and the recommended approach. Here, the client sends data as a continuous stream, and the **Weaviate server manages the data flow**.
-### Server-side batching
-
-Server-side batching, or **automatic mode**, is a more robust and the recommended approach. Here, the client sends data as a continuous stream, and the **Weaviate server intelligently manages the data flow**.
-
-Using an internal queue and a dynamic **backpressure** mechanism, the server tells the client how much data to send next based on its current workload. This simplifies your client code, eliminates the need for manual tuning, and results in a more efficient and resilient data import process.
+ Using an internal queue and a dynamic _[backpressure](https://en.wikipedia.org/wiki/Backpressure_routing)_ mechanism, the server tells the client how much data to send next based on its current workload. This simplifies your client code, eliminates the need for manual tuning, and results in a more efficient and resilient data import process.
:::tip
@@ -27,7 +25,7 @@ For **code examples**, check out the [How-to: Batch import](../manage-objects/im
---
-## Server-side batching (Automatic mode)
+## Server-side batching
Weaviate's server-side batching, also known as **automatic batching**, is an intelligent mechanism designed to make data ingestion simpler, faster, and more robust. Instead of manually tuning batch parameters on the client side, you can let the server dynamically manage the data flow for optimal performance.
@@ -37,14 +35,14 @@ This mode is a drop-in replacement for `fixed_size` or `dynamic` batching and is
When you use the `automatic()` batching context manager, you initiate a persistent connection to the server for the duration of the batch job.
-1. **Client Sends Data**: Your client sends objects to the server in chunks. These requests execute instantly without waiting for the data to be fully imported.
-2. **Server Manages Queues**: The server places incoming objects into an internal queue system. This decouples the network communication from the actual database work (like vectorization and storage).
-3. **Dynamic Backpressure**: The server continuously monitors its internal queue size. It calculates an exponential moving average (EMA) of its workload and tells the client the ideal number of objects to send in the next chunk. This feedback loop allows the system to self-regulate, maximizing throughput without overwhelming the server.
-4. **Asynchronous Errors**: If an error occurs while processing an object (e.g., validation fails), the server sends the error message back to the client over a separate, dedicated stream without interrupting the flow of other objects.
+1. **Client sends data**: Your client sends objects to the server in chunks. These requests execute instantly without waiting for the data to be fully imported.
+2. **Server manages queues**: The server places incoming objects into an internal queue system. This decouples the network communication from the actual database work (like vectorization and storage).
+3. **Dynamic backpressure**: The server continuously monitors its internal queue size. It calculates an exponential moving average (EMA) of its workload and tells the client the ideal number of objects to send in the next chunk. This feedback loop allows the system to self-regulate, maximizing throughput without overwhelming the server.
+4. **Asynchronous errors**: If an error occurs while processing an object (e.g., validation fails), the server sends the error message back to the client over a separate, dedicated stream without interrupting the flow of other objects.
This architecture centralizes the complex batching logic on the server, resulting in a more efficient and stable data ingestion pipeline for all connected clients.
-:::info Why use automatic batching?
+:::info Why use automatic (server-side) batching?
- **Simplified client code**: No need to tweak `batch_size` and `concurrent_requests` manually. The server determines the optimal batch size based on its current workload.
- **Improved stability**: The system automatically applies **backpressure**. If the server is busy, it will instruct the client to send less data, preventing overloads and request timeouts, which is especially useful during long-running vectorization tasks.
From 81025ed97834fc42d1349585e580368912a5d63a Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Tue, 26 Aug 2025 11:43:12 +0200
Subject: [PATCH 05/44] Update docs
---
docs/weaviate/concepts/data-import.mdx | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/docs/weaviate/concepts/data-import.mdx b/docs/weaviate/concepts/data-import.mdx
index 48e19a47..44f5f053 100644
--- a/docs/weaviate/concepts/data-import.mdx
+++ b/docs/weaviate/concepts/data-import.mdx
@@ -27,6 +27,14 @@ For **code examples**, check out the [How-to: Batch import](../manage-objects/im
## Server-side batching
+:::caution Technical preview
+
+Server-side batching was added in **`v1.33`** as a **technical preview**.
+This means that the feature is still under development and may change in future releases, including potential breaking changes.
+**We do not recommend using this feature in production environments at this time.**
+
+:::
+
Weaviate's server-side batching, also known as **automatic batching**, is an intelligent mechanism designed to make data ingestion simpler, faster, and more robust. Instead of manually tuning batch parameters on the client side, you can let the server dynamically manage the data flow for optimal performance.
This mode is a drop-in replacement for `fixed_size` or `dynamic` batching and is the recommended method for importing data.
From 3b66388281ffd8c302abfee90a5c834708c56765 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 12:04:22 +0200
Subject: [PATCH 06/44] Add OIDC testing
---
.gitignore | 4 +
.../howto.configure.rbac.oidc.groups.py | 500 ++++++++++++++++++
.../code/python/keycloak_helper_script.py | 493 +++++++++++++++++
tests/docker-compose-anon.yml | 2 +-
tests/docker-compose-rbac.yml | 42 +-
5 files changed, 1036 insertions(+), 5 deletions(-)
create mode 100644 _includes/code/python/howto.configure.rbac.oidc.groups.py
create mode 100644 _includes/code/python/keycloak_helper_script.py
diff --git a/.gitignore b/.gitignore
index e807b5f2..2e4793da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -258,3 +258,7 @@ __marimo__/
# Streamlit
.streamlit/secrets.toml
+
+# C# code
+_includes/code/csharp/bin
+_includes/code/csharp/obj
diff --git a/_includes/code/python/howto.configure.rbac.oidc.groups.py b/_includes/code/python/howto.configure.rbac.oidc.groups.py
new file mode 100644
index 00000000..b1dea599
--- /dev/null
+++ b/_includes/code/python/howto.configure.rbac.oidc.groups.py
@@ -0,0 +1,500 @@
+#!/usr/bin/env python3
+"""
+OIDC Group Management Testing Script with Built-in Keycloak Setup Helper
+Complete example of how to configure RBAC with OIDC groups in Weaviate
+"""
+
+import requests
+import json
+import sys
+from typing import Dict, Any, Optional
+import weaviate
+from weaviate.classes.init import Auth
+from weaviate.classes.rbac import Permissions
+
+def test_keycloak_connection(keycloak_ports: list = [8081]) -> Optional[str]:
+ """Test if Keycloak is accessible on common ports"""
+ # Try keycloak hostname first (requires /etc/hosts mapping), then localhost
+ keycloak_configs = [
+ ("keycloak", 8081), # This should match Weaviate's expected issuer
+ ("localhost", 8081) # Fallback for initial testing
+ ]
+
+ for host, port in keycloak_configs:
+ keycloak_url = f"http://{host}:{port}"
+ try:
+ # First check if Keycloak is responding at all
+ response = requests.get(f"{keycloak_url}", timeout=5)
+ if response.status_code == 200:
+ print(f"✅ Keycloak server found at {keycloak_url}")
+
+ # Check if master realm exists (always exists)
+ master_response = requests.get(f"{keycloak_url}/realms/master", timeout=5)
+ if master_response.status_code == 200:
+ print(f"✅ Keycloak realms accessible")
+
+ # Check if our test realm exists
+ test_response = requests.get(f"{keycloak_url}/realms/weaviate-test", timeout=5)
+ if test_response.status_code == 200:
+ print(f"✅ weaviate-test realm found")
+ print(f"✅ weaviate-test realm accessible")
+ return keycloak_url
+ else:
+ print(f"⚠️ weaviate-test realm not found - you'll need to create it")
+ return keycloak_url
+ except Exception as e:
+ print(f"Testing {keycloak_url}: {e}")
+ continue
+
+ print(f"❌ Cannot connect to Keycloak")
+ print("💡 Make sure you have '127.0.0.1 keycloak' in /etc/hosts")
+ print("💡 Run: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts")
+ return None
+
+def get_client_secret_instructions():
+ """Print instructions for getting client secret"""
+ print("\n" + "="*60)
+ print("📋 KEYCLOAK SETUP INSTRUCTIONS")
+ print("="*60)
+ print("Your Keycloak is running! Now you need to set it up:")
+ print("")
+ print("1. 🌐 Go to http://keycloak:8081 (make sure you have keycloak in /etc/hosts)")
+ print("2. 🔑 Login with username: admin, password: admin")
+ print("3. 🏛️ CREATE REALM:")
+ print(" - Click dropdown next to 'master' (top-left)")
+ print(" - Click 'Create Realm'")
+ print(" - Realm name: weaviate-test")
+ print(" - Click 'Create'")
+ print("")
+ print("4. 📱 CREATE CLIENT:")
+ print(" - Go to 'Clients' → 'Create client'")
+ print(" - Client ID: weaviate")
+ print(" - Client type: OpenID Connect")
+ print(" - Click 'Next'")
+ print(" - Enable 'Client authentication'")
+ print(" - Enable 'Direct access grants'")
+ print(" - Click 'Save'")
+ print("")
+ print("5. 🔐 GET CLIENT SECRET:")
+ print(" - Go to 'Credentials' tab")
+ print(" - Copy the 'Client secret' value")
+ print("")
+ print("6. 👥 CREATE GROUPS:")
+ print(" - Go to 'Groups'")
+ print(" - Create: /admin-group, /viewer-group, /my-test-group")
+ print("")
+ print("7. 👤 CREATE USERS:")
+ print(" - Go to 'Users' → 'Create new user'")
+ print(" - Username: test-admin, set password: password123")
+ print(" - Add to groups: /admin-group, /my-test-group")
+ print(" - Create test-viewer user, add to /viewer-group")
+ print("")
+ print("8. ⚙️ CONFIGURE GROUP CLAIMS:")
+ print(" - Go to 'Client scopes' → 'weaviate-dedicated'")
+ print(" - Add mapper → Group Membership")
+ print(" - Name: groups, Token Claim Name: groups")
+ print(" - Add to ID token: ON, Add to access token: ON")
+ print("="*60)
+
+def get_oidc_token(
+ keycloak_url: str = "http://keycloak:8081", # Changed default to keycloak hostname
+ realm: str = "weaviate-test",
+ client_id: str = "weaviate",
+ client_secret: str = "",
+ username: str = "test-admin",
+ password: str = "password123"
+) -> Optional[str]:
+ """Get OIDC token from Keycloak for a user"""
+ token_url = f"{keycloak_url}/realms/{realm}/protocol/openid-connect/token"
+
+ data = {
+ "grant_type": "password",
+ "client_id": client_id,
+ "client_secret": client_secret,
+ "username": username,
+ "password": password
+ }
+
+ try:
+ response = requests.post(token_url, data=data, timeout=10)
+
+ if response.status_code == 200:
+ token_data = response.json()
+ print(f"✅ Successfully got token for user: {username}")
+ return token_data["access_token"]
+ else:
+ print(f"❌ Failed to get token for {username}: {response.status_code}")
+ if response.status_code == 401:
+ print(" → Check username/password or client secret")
+ elif response.status_code == 400:
+ print(" → Check client configuration (Direct Access Grants enabled?)")
+ print(f" → Response: {response.text}")
+ return None
+
+ except Exception as e:
+ print(f"❌ Error getting token for {username}: {e}")
+ return None
+
+def decode_token_groups(token: str) -> Dict[str, Any]:
+ """Decode JWT token to see groups (for debugging)"""
+ try:
+ import jwt
+ decoded = jwt.decode(token, options={"verify_signature": False})
+ return decoded
+ except ImportError:
+ print("⚠️ Install PyJWT to see token details: pip install PyJWT")
+ return {}
+ except Exception as e:
+ print(f"⚠️ Error decoding token: {e}")
+ return {}
+
+def show_token_info(token: str, username: str):
+ """Display token information"""
+ decoded = decode_token_groups(token)
+ if decoded:
+ print(f" → Username: {decoded.get('preferred_username', 'N/A')}")
+ print(f" → Groups: {decoded.get('groups', [])}")
+ print(f" → Issuer: {decoded.get('iss', 'N/A')}")
+ print(f" → Realm roles: {decoded.get('realm_access', {}).get('roles', [])}")
+
+def run_automated_setup(keycloak_url: str) -> Optional[str]:
+ """Run automated Keycloak setup using Admin API"""
+ try:
+ # Import the automated setup class inline
+ import requests
+ from typing import Optional, Dict
+
+ class KeycloakSetup:
+ def __init__(self, keycloak_url: str = "http://keycloak:8081", admin_user: str = "admin", admin_pass: str = "admin"):
+ self.keycloak_url = keycloak_url.rstrip("/")
+ self.admin_user = admin_user
+ self.admin_pass = admin_pass
+ self.admin_token = None
+ self.realm_name = "weaviate-test"
+ self.client_id = "weaviate"
+
+ def get_admin_token(self) -> Optional[str]:
+ token_url = f"{self.keycloak_url}/realms/master/protocol/openid-connect/token"
+ data = {
+ "grant_type": "password",
+ "client_id": "admin-cli",
+ "username": self.admin_user,
+ "password": self.admin_pass,
+ }
+ try:
+ response = requests.post(token_url, data=data, timeout=10)
+ if response.status_code == 200:
+ self.admin_token = response.json()["access_token"]
+ return self.admin_token
+ return None
+ except Exception:
+ return None
+
+ def make_admin_request(self, method: str, endpoint: str, json_data: Dict = None) -> requests.Response:
+ headers = {
+ "Authorization": f"Bearer {self.admin_token}",
+ "Content-Type": "application/json",
+ }
+ url = f"{self.keycloak_url}/admin/realms{endpoint}"
+ if method.upper() == "GET":
+ return requests.get(url, headers=headers, timeout=10)
+ elif method.upper() == "POST":
+ return requests.post(url, headers=headers, json=json_data, timeout=10)
+
+ def create_realm(self) -> bool:
+ response = self.make_admin_request("GET", f"/{self.realm_name}")
+ if response.status_code == 200:
+ return True
+ realm_config = {"realm": self.realm_name, "enabled": True}
+ response = self.make_admin_request("POST", "", realm_config)
+ return response.status_code == 201
+
+ def create_client(self) -> Optional[str]:
+ client_config = {
+ "clientId": self.client_id,
+ "enabled": True,
+ "clientAuthenticatorType": "client-secret",
+ "secret": "weaviate-client-secret-123",
+ "redirectUris": ["*"],
+ "standardFlowEnabled": True,
+ "directAccessGrantsEnabled": True,
+ "publicClient": False,
+ }
+ response = self.make_admin_request("POST", f"/{self.realm_name}/clients", client_config)
+ if response.status_code == 201:
+ return "weaviate-client-secret-123"
+ return None
+
+ def setup_all(self) -> Optional[str]:
+ if not self.get_admin_token():
+ return None
+ if not self.create_realm():
+ return None
+ return self.create_client()
+
+ print("🤖 Running automated Keycloak setup...")
+ setup = KeycloakSetup(keycloak_url)
+ client_secret = setup.setup_all()
+
+ if client_secret:
+ print(f"\n🎉 Automated setup completed successfully!")
+ return client_secret
+ else:
+ print("❌ Automated setup failed")
+ return None
+ except Exception as e:
+ print(f"❌ Automated setup error: {e}")
+ return None
+
+def setup_and_validate_oidc() -> tuple[Optional[str], Optional[str]]:
+ """Setup and validate OIDC connection, return (client_secret, keycloak_url) if successful"""
+ print("🧪 KEYCLOAK OIDC SETUP VALIDATOR")
+ print("=" * 50)
+
+ # Test Keycloak connection
+ print("Testing Keycloak connection...")
+ keycloak_url = test_keycloak_connection([8081])
+ if not keycloak_url:
+ print("❌ Keycloak not accessible!")
+ print("\nTroubleshooting:")
+ print("1. Add keycloak to /etc/hosts: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts")
+ print("2. Check if docker-compose is running: docker-compose ps")
+ print("3. Check Keycloak logs: docker-compose logs keycloak")
+ return None, None
+
+ # Check if weaviate-test realm exists
+ try:
+ realm_response = requests.get(f"{keycloak_url}/realms/weaviate-test", timeout=5)
+ realm_exists = realm_response.status_code == 200
+ except:
+ realm_exists = False
+
+ if not realm_exists:
+ print(f"\n⚠️ The 'weaviate-test' realm doesn't exist yet.")
+ print("Choose your setup method:")
+ print("1. 🤖 Automated setup (recommended)")
+ print("2. 📋 Manual setup instructions")
+
+ choice = input("\nEnter choice (1 or 2): ").strip()
+
+ if choice == "1":
+ client_secret = run_automated_setup(keycloak_url)
+ if not client_secret:
+ return None, None
+ else:
+ get_client_secret_instructions()
+ setup_choice = input("\nHave you completed the manual setup? (y/n): ").strip().lower()
+ if setup_choice != 'y':
+ print("Please complete the Keycloak setup first, then run this script again.")
+ return None, None
+ client_secret = input("Enter Keycloak client secret: ").strip()
+ if not client_secret:
+ print("❌ Client secret required.")
+ return None, None
+ else:
+ print(f"✅ weaviate-test realm accessible")
+ print("\n" + "-"*30)
+ client_secret = input("Enter Keycloak client secret (or 'auto' for automated setup): ").strip()
+
+ if client_secret.lower() == 'auto':
+ client_secret = run_automated_setup(keycloak_url)
+ if not client_secret:
+ return None, None
+ elif not client_secret:
+ print("❌ Client secret required.")
+ return None, None
+
+ # Test tokens with the keycloak_url (which should be http://keycloak:8081)
+ print(f"\n🔑 Testing OIDC tokens...")
+ admin_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin")
+
+ if not admin_token:
+ print("\n❌ Cannot get admin token. Please verify:")
+ print("- User 'test-admin' exists with password 'password123'")
+ print("- User is in groups like '/admin-group'")
+ print("- Client 'weaviate' has 'Direct access grants' enabled")
+ print("- Client secret is correct")
+ return None, None
+
+ show_token_info(admin_token, "test-admin")
+
+ viewer_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer")
+ if viewer_token:
+ show_token_info(viewer_token, "test-viewer")
+ else:
+ print("⚠️ Viewer token failed, but continuing with admin token")
+
+ print("\n✅ OIDC setup validated successfully!")
+ return client_secret, keycloak_url
+
+def main():
+ """Main function to run OIDC group management tests"""
+
+ # Setup and validate OIDC first
+ client_secret, keycloak_url = setup_and_validate_oidc()
+ if not client_secret or not keycloak_url:
+ sys.exit(1)
+
+ print("\n" + "="*60)
+ print("🚀 STARTING OIDC GROUP MANAGEMENT TESTS")
+ print("="*60)
+
+ # START AdminClient
+ # Connect to Weaviate as root user (for admin operations)
+ admin_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.api_key("root-user-key"),
+ )
+ # END AdminClient
+
+ # Create test roles for group management
+ print("\n📋 Setting up test roles...")
+ permissions = [
+ Permissions.collections(
+ collection="TargetCollection*", read_config=True, create_collection=True
+ ),
+ Permissions.data(collection="TargetCollection*", read=True, create=True),
+ ]
+
+ admin_client.roles.delete(role_name="testRole")
+ admin_client.roles.create(role_name="testRole", permissions=permissions)
+
+ admin_client.roles.delete(role_name="groupViewerRole")
+ admin_client.roles.create(role_name="groupViewerRole", permissions=[
+ Permissions.data(collection="*", read=True)
+ ])
+
+ print("\n🔧 ADMIN OPERATIONS (Using API Key)")
+ print("-" * 40)
+
+ # START AssignOidcGroupRoles
+ admin_client.groups.oidc.assign_roles(group_id="/admin-group", role_names=["testRole", "viewer"])
+ admin_client.groups.oidc.assign_roles(group_id="/viewer-group", role_names=["viewer"])
+ admin_client.groups.oidc.assign_roles(group_id="/my-test-group", role_names=["groupViewerRole"])
+ print("✅ Assigned roles to OIDC groups")
+ # END AssignOidcGroupRoles
+
+ # START GetKnownOidcGroups
+ known_groups = admin_client.groups.oidc.get_known_group_names()
+ print(f"📁 Known OIDC groups ({len(known_groups)}):")
+ for group in known_groups:
+ print(f" - {group}")
+ # END GetKnownOidcGroups
+
+ # START GetGroupAssignments
+ group_assignments = admin_client.roles.get_group_assignments(role_name="testRole")
+ print(f"👥 Groups assigned to role 'testRole':")
+ for group in group_assignments:
+ print(f" - Group ID: {group.group_id}")
+ print(f" Group Type: {group.group_type}")
+ # END GetGroupAssignments
+
+ admin_client.close()
+
+ print(f"\n👤 OIDC USER OPERATIONS")
+ print("-" * 40)
+
+ # Get tokens for different users using keycloak_url
+ # START GetOidcToken
+ admin_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin")
+ viewer_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer")
+ # END GetOidcToken
+
+ if admin_token:
+ # START OidcAdminClient
+ # Connect as OIDC admin user
+ oidc_admin_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.bearer_token(admin_token),
+ )
+ # END OidcAdminClient
+
+ try:
+ # START GetCurrentUserRoles
+ my_user = oidc_admin_client.users.get_my_user()
+ current_roles = my_user.roles if my_user else []
+ print(f"🔑 Admin user's current roles ({len(current_roles)}):")
+ for role in current_roles:
+ print(f" - {role}")
+ # END GetCurrentUserRoles
+
+ # Test admin can see group assignments (if they have permissions)
+ try:
+ # START GetOidcGroupRoles
+ group_roles = oidc_admin_client.groups.oidc.get_assigned_roles(
+ group_id="/admin-group",
+ include_permissions=True
+ )
+ print(f"👑 Admin group roles:")
+ for role_name, role_obj in group_roles.items():
+ print(f" - {role_name}")
+ # END GetOidcGroupRoles
+ except Exception as e:
+ print(f"⚠️ Admin user cannot access group details: {e}")
+
+ except Exception as e:
+ print(f"❌ Error with admin OIDC operations: {e}")
+ finally:
+ oidc_admin_client.close()
+
+ if viewer_token:
+ # START OidcViewerClient
+ # Connect as OIDC viewer user
+ oidc_viewer_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.bearer_token(viewer_token),
+ )
+ # END OidcViewerClient
+
+ try:
+ # START GetCurrentUserRolesViewer
+ my_user = oidc_viewer_client.users.get_my_user()
+ current_roles = my_user.roles if my_user else []
+ print(f"👀 Viewer user's current roles ({len(current_roles)}):")
+ for role in current_roles:
+ print(f" - {role}")
+ # END GetCurrentUserRolesViewer
+
+ # Viewer should have limited permissions
+ try:
+ viewer_groups = oidc_viewer_client.groups.oidc.get_known_group_names()
+ print(f"👀 Viewer can see groups: {viewer_groups}")
+ except Exception as e:
+ print(f"⚠️ Viewer user cannot access group operations: {e}")
+
+ except Exception as e:
+ print(f"❌ Error with viewer OIDC operations: {e}")
+ finally:
+ oidc_viewer_client.close()
+
+ print(f"\n🧹 CLEANUP (Admin operations)")
+ print("-" * 40)
+
+ # Reconnect as admin for cleanup
+ admin_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.api_key("root-user-key"),
+ )
+
+ # START RevokeOidcGroupRoles
+ admin_client.groups.oidc.revoke_roles(group_id="/admin-group", role_names=["testRole", "viewer"])
+ admin_client.groups.oidc.revoke_roles(group_id="/viewer-group", role_names=["viewer"])
+ admin_client.groups.oidc.revoke_roles(group_id="/my-test-group", role_names=["groupViewerRole"])
+ print("✅ Revoked all assigned group roles")
+ # END RevokeOidcGroupRoles
+
+ # Verify cleanup
+ final_groups = admin_client.groups.oidc.get_known_group_names()
+ print(f"📁 Remaining known groups after cleanup: {final_groups}")
+
+ admin_client.close()
+
+ print(f"\n🎉 OIDC GROUP MANAGEMENT TESTING COMPLETE!")
+ print("="*60)
+
+if __name__ == "__main__":
+ main()
\ No newline at end of file
diff --git a/_includes/code/python/keycloak_helper_script.py b/_includes/code/python/keycloak_helper_script.py
new file mode 100644
index 00000000..c9f0eda0
--- /dev/null
+++ b/_includes/code/python/keycloak_helper_script.py
@@ -0,0 +1,493 @@
+#!/usr/bin/env python3
+"""
+Automated Keycloak Setup Script
+Creates realm, client, users, groups, and configures everything needed for OIDC testing
+"""
+
+import requests
+import json
+import time
+from typing import Optional, Dict, Any
+
+
+class KeycloakSetup:
+ def __init__(
+ self,
+ keycloak_url: str = "http://localhost:8081",
+ admin_user: str = "admin",
+ admin_pass: str = "admin",
+ ):
+ self.keycloak_url = keycloak_url.rstrip("/")
+ self.admin_user = admin_user
+ self.admin_pass = admin_pass
+ self.admin_token = None
+ self.realm_name = "weaviate-test"
+ self.client_id = "weaviate"
+
+ def get_admin_token(self) -> Optional[str]:
+ """Get admin token from master realm"""
+ print("🔑 Getting admin token...")
+
+ token_url = f"{self.keycloak_url}/realms/master/protocol/openid-connect/token"
+ data = {
+ "grant_type": "password",
+ "client_id": "admin-cli",
+ "username": self.admin_user,
+ "password": self.admin_pass,
+ }
+
+ try:
+ response = requests.post(token_url, data=data, timeout=10)
+ if response.status_code == 200:
+ self.admin_token = response.json()["access_token"]
+ print("✅ Got admin token")
+ return self.admin_token
+ else:
+ print(f"❌ Failed to get admin token: {response.status_code}")
+ print(f"Response: {response.text}")
+ return None
+ except Exception as e:
+ print(f"❌ Error getting admin token: {e}")
+ return None
+
+ def make_admin_request(
+ self, method: str, endpoint: str, json_data: Dict = None
+ ) -> requests.Response:
+ """Make authenticated request to Keycloak Admin API"""
+ if not self.admin_token:
+ raise Exception("No admin token available")
+
+ headers = {
+ "Authorization": f"Bearer {self.admin_token}",
+ "Content-Type": "application/json",
+ }
+
+ url = f"{self.keycloak_url}/admin/realms{endpoint}"
+
+ if method.upper() == "GET":
+ return requests.get(url, headers=headers, timeout=10)
+ elif method.upper() == "POST":
+ return requests.post(url, headers=headers, json=json_data, timeout=10)
+ elif method.upper() == "PUT":
+ return requests.put(url, headers=headers, json=json_data, timeout=10)
+ elif method.upper() == "DELETE":
+ return requests.delete(url, headers=headers, timeout=10)
+ else:
+ raise ValueError(f"Unsupported HTTP method: {method}")
+
+ def create_realm(self) -> bool:
+ """Create the weaviate-test realm"""
+ print(f"🏛️ Creating realm '{self.realm_name}'...")
+
+ # Check if realm already exists
+ response = self.make_admin_request("GET", f"/{self.realm_name}")
+ if response.status_code == 200:
+ print(f"✅ Realm '{self.realm_name}' already exists")
+ return True
+
+ # Create realm
+ realm_config = {
+ "realm": self.realm_name,
+ "enabled": True,
+ "displayName": "Weaviate Test Realm",
+ "registrationAllowed": False,
+ "loginWithEmailAllowed": True,
+ "duplicateEmailsAllowed": False,
+ "rememberMe": True,
+ "verifyEmail": False,
+ "loginTheme": None,
+ "accountTheme": None,
+ "adminTheme": None,
+ "emailTheme": None,
+ }
+
+ response = self.make_admin_request("POST", "", realm_config)
+ if response.status_code == 201:
+ print(f"✅ Created realm '{self.realm_name}'")
+ return True
+ else:
+ print(f"❌ Failed to create realm: {response.status_code}")
+ print(f"Response: {response.text}")
+ return False
+
+ def create_client(self) -> Optional[str]:
+ """Create the weaviate client and return client secret"""
+ print(f"📱 Creating client '{self.client_id}'...")
+
+ # Check if client already exists
+ response = self.make_admin_request("GET", f"/{self.realm_name}/clients")
+ if response.status_code == 200:
+ clients = response.json()
+ for client in clients:
+ if client.get("clientId") == self.client_id:
+ print(f"✅ Client '{self.client_id}' already exists")
+ client_uuid = client["id"]
+ return self.get_client_secret(client_uuid)
+
+ # Create client
+ client_config = {
+ "clientId": self.client_id,
+ "name": "Weaviate OIDC Client",
+ "enabled": True,
+ "clientAuthenticatorType": "client-secret",
+ "secret": "weaviate-client-secret-123", # Fixed secret for easier testing
+ "redirectUris": ["*"],
+ "webOrigins": ["*"],
+ "standardFlowEnabled": True,
+ "directAccessGrantsEnabled": True, # Enable Direct Access Grants
+ "serviceAccountsEnabled": True,
+ "publicClient": False,
+ "protocol": "openid-connect",
+ "attributes": {
+ "saml.assertion.signature": "false",
+ "saml.force.post.binding": "false",
+ "saml.multivalued.roles": "false",
+ "saml.encrypt": "false",
+ "saml.server.signature": "false",
+ "saml.server.signature.keyinfo.ext": "false",
+ "exclude.session.state.from.auth.response": "false",
+ "saml_force_name_id_format": "false",
+ "saml.client.signature": "false",
+ "tls.client.certificate.bound.access.tokens": "false",
+ "saml.authnstatement": "false",
+ "display.on.consent.screen": "false",
+ "saml.onetimeuse.condition": "false",
+ },
+ }
+
+ response = self.make_admin_request(
+ "POST", f"/{self.realm_name}/clients", client_config
+ )
+ if response.status_code == 201:
+ print(f"✅ Created client '{self.client_id}'")
+
+ # Get the client UUID
+ response = self.make_admin_request("GET", f"/{self.realm_name}/clients")
+ clients = response.json()
+ for client in clients:
+ if client.get("clientId") == self.client_id:
+ client_uuid = client["id"]
+ return self.get_client_secret(client_uuid)
+ else:
+ print(f"❌ Failed to create client: {response.status_code}")
+ print(f"Response: {response.text}")
+ return None
+
+ def get_client_secret(self, client_uuid: str) -> Optional[str]:
+ """Get client secret"""
+ response = self.make_admin_request(
+ "GET", f"/{self.realm_name}/clients/{client_uuid}/client-secret"
+ )
+ if response.status_code == 200:
+ secret = response.json().get("value")
+ print(f"🔐 Client secret: {secret}")
+ return secret
+ return None
+
+ def create_groups(self) -> bool:
+ """Create test groups"""
+ print("👥 Creating groups...")
+
+ groups_to_create = [
+ {"name": "admin-group", "path": "/admin-group"},
+ {"name": "viewer-group", "path": "/viewer-group"},
+ {"name": "my-test-group", "path": "/my-test-group"},
+ {"name": "another-test-group", "path": "/another-test-group"},
+ ]
+
+ for group_config in groups_to_create:
+ # Check if group exists
+ response = self.make_admin_request("GET", f"/{self.realm_name}/groups")
+ if response.status_code == 200:
+ existing_groups = response.json()
+ group_exists = any(
+ g.get("path") == group_config["path"] for g in existing_groups
+ )
+
+ if group_exists:
+ print(f"✅ Group '{group_config['path']}' already exists")
+ continue
+
+ # Create group
+ response = self.make_admin_request(
+ "POST", f"/{self.realm_name}/groups", group_config
+ )
+ if response.status_code == 201:
+ print(f"✅ Created group '{group_config['path']}'")
+ else:
+ print(
+ f"❌ Failed to create group '{group_config['path']}': {response.status_code}"
+ )
+ return False
+
+ return True
+
+ def create_users(self) -> bool:
+ """Create test users"""
+ print("👤 Creating users...")
+
+ users_to_create = [
+ {
+ "username": "test-admin",
+ "email": "admin@test.com",
+ "firstName": "Test",
+ "lastName": "Admin",
+ "password": "password123",
+ "groups": ["/admin-group", "/my-test-group"],
+ },
+ {
+ "username": "test-viewer",
+ "email": "viewer@test.com",
+ "firstName": "Test",
+ "lastName": "Viewer",
+ "password": "password123",
+ "groups": ["/viewer-group"],
+ },
+ ]
+
+ for user_config in users_to_create:
+ # Check if user exists
+ response = self.make_admin_request(
+ "GET", f"/{self.realm_name}/users?username={user_config['username']}"
+ )
+ if response.status_code == 200 and response.json():
+ print(f"✅ User '{user_config['username']}' already exists")
+ continue
+
+ # Create user
+ user_data = {
+ "username": user_config["username"],
+ "email": user_config["email"],
+ "firstName": user_config["firstName"],
+ "lastName": user_config["lastName"],
+ "enabled": True,
+ "emailVerified": True,
+ }
+
+ response = self.make_admin_request(
+ "POST", f"/{self.realm_name}/users", user_data
+ )
+ if response.status_code == 201:
+ print(f"✅ Created user '{user_config['username']}'")
+
+ # Get user ID from location header
+ user_id = response.headers["Location"].split("/")[-1]
+
+ # Set password
+ password_data = {
+ "type": "password",
+ "value": user_config["password"],
+ "temporary": False,
+ }
+
+ pwd_response = self.make_admin_request(
+ "PUT",
+ f"/{self.realm_name}/users/{user_id}/reset-password",
+ password_data,
+ )
+ if pwd_response.status_code == 204:
+ print(f"✅ Set password for '{user_config['username']}'")
+
+ # Add user to groups
+ self.add_user_to_groups(user_id, user_config["groups"])
+
+ else:
+ print(
+ f"❌ Failed to create user '{user_config['username']}': {response.status_code}"
+ )
+ return False
+
+ return True
+
+ def add_user_to_groups(self, user_id: str, group_paths: list):
+ """Add user to specified groups"""
+ # Get all groups
+ response = self.make_admin_request("GET", f"/{self.realm_name}/groups")
+ if response.status_code != 200:
+ print("❌ Failed to get groups")
+ return
+
+ all_groups = response.json()
+
+ for group_path in group_paths:
+ # Find group by path
+ group_id = None
+ for group in all_groups:
+ if group.get("path") == group_path:
+ group_id = group["id"]
+ break
+
+ if group_id:
+ # Add user to group
+ response = self.make_admin_request(
+ "PUT", f"/{self.realm_name}/users/{user_id}/groups/{group_id}", {}
+ )
+ if response.status_code == 204:
+ print(f"✅ Added user to group '{group_path}'")
+ else:
+ print(
+ f"❌ Failed to add user to group '{group_path}': {response.status_code}"
+ )
+ else:
+ print(f"❌ Group '{group_path}' not found")
+
+ def configure_group_mapper(self, client_uuid: str) -> bool:
+ """Configure group membership mapper directly on the client."""
+ print("⚙️ Configuring group mapper...")
+
+ mapper_config = {
+ "name": "groups",
+ "protocol": "openid-connect",
+ "protocolMapper": "oidc-group-membership-mapper",
+ "consentRequired": False,
+ "config": {
+ "full.path": "true", # Use true for full path like /admin-group
+ "id.token.claim": "true",
+ "access.token.claim": "true",
+ "claim.name": "groups",
+ "userinfo.token.claim": "true",
+ },
+ }
+
+ # The endpoint is now directly on the client
+ response = self.make_admin_request(
+ "POST",
+ f"/{self.realm_name}/clients/{client_uuid}/protocol-mappers/models",
+ mapper_config,
+ )
+
+ if response.status_code == 201:
+ print("✅ Configured group membership mapper")
+ return True
+ elif response.status_code == 409: # 409 Conflict means it already exists
+ print("✅ Group membership mapper already exists")
+ return True
+ else:
+ print(f"❌ Failed to configure group mapper: {response.status_code}")
+ print(f"Response: {response.text}")
+ return False
+
+ def configure_audience_mapper(self, client_uuid: str) -> bool:
+ """Configure audience mapper directly on the client."""
+ print("⚙️ Configuring audience mapper...")
+
+ mapper_config = {
+ "name": "weaviate-audience",
+ "protocol": "openid-connect",
+ "protocolMapper": "oidc-audience-mapper",
+ "config": {
+ "id.token.claim": "false",
+ "access.token.claim": "true",
+ "included.client.audience": self.client_id,
+ },
+ }
+
+ # The endpoint is now directly on the client
+ response = self.make_admin_request(
+ "POST",
+ f"/{self.realm_name}/clients/{client_uuid}/protocol-mappers/models",
+ mapper_config,
+ )
+
+ if response.status_code == 201:
+ print("✅ Configured audience mapper")
+ return True
+ elif response.status_code == 409: # 409 Conflict means it already exists
+ print("✅ Audience mapper already exists")
+ return True
+ else:
+ print(f"❌ Failed to configure audience mapper: {response.status_code}")
+ print(f"Response: {response.text}")
+ return False
+
+ def setup_all(self) -> Optional[str]:
+ """Run complete setup process"""
+ print("🚀 AUTOMATED KEYCLOAK SETUP")
+ print("=" * 50)
+
+ # Get admin token
+ if not self.get_admin_token():
+ return None
+
+ # Create realm
+ if not self.create_realm():
+ return None
+
+ # Create client and get secret
+ client_secret = self.create_client()
+ if not client_secret:
+ return None
+
+ # Create groups
+ if not self.create_groups():
+ return None
+
+ # Create users
+ if not self.create_users():
+ return None
+
+ # Get client UUID for mapper configuration
+ response = self.make_admin_request("GET", f"/{self.realm_name}/clients")
+ client_uuid = None
+ if response.status_code == 200:
+ clients = response.json()
+ for client in clients:
+ if client.get("clientId") == self.client_id:
+ client_uuid = client["id"]
+ break
+
+ if client_uuid:
+ self.configure_group_mapper(client_uuid)
+ self.configure_audience_mapper(client_uuid)
+
+ print("\n🎉 KEYCLOAK SETUP COMPLETE!")
+ print("=" * 50)
+ print(f"🌐 Keycloak URL: {self.keycloak_url}")
+ print(f"🏛️ Realm: {self.realm_name}")
+ print(f"📱 Client ID: {self.client_id}")
+ print(f"🔐 Client Secret: {client_secret}")
+ print("\n👤 Test Users:")
+ print(" - Username: test-admin, Password: password123")
+ print(" Groups: /admin-group, /my-test-group")
+ print(" - Username: test-viewer, Password: password123")
+ print(" Groups: /viewer-group")
+
+ return client_secret
+
+
+def main():
+ """Main function to run automated setup"""
+
+ # Test multiple ports
+ for port in [8081, 8082]:
+ keycloak_url = f"http://localhost:{port}"
+ print(f"Testing Keycloak at {keycloak_url}...")
+
+ try:
+ response = requests.get(keycloak_url, timeout=5)
+ if response.status_code == 200:
+ print(f"✅ Found Keycloak at {keycloak_url}")
+
+ # Run automated setup
+ setup = KeycloakSetup(keycloak_url)
+ client_secret = setup.setup_all()
+
+ if client_secret:
+ print(f"\n🔧 Your client secret for the Python script:")
+ print(f" {client_secret}")
+ print(f"\n▶️ Now run your OIDC Python script!")
+ return
+ else:
+ print("❌ Setup failed")
+ return
+
+ except Exception as e:
+ print(f"Cannot connect to {keycloak_url}: {e}")
+ continue
+
+ print("❌ Keycloak not found on ports 8081 or 8082")
+ print("Make sure docker-compose is running!")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/docker-compose-anon.yml b/tests/docker-compose-anon.yml
index 4052eda7..fae03eaa 100644
--- a/tests/docker-compose-anon.yml
+++ b/tests/docker-compose-anon.yml
@@ -8,7 +8,7 @@ services:
- '8080'
- --scheme
- http
- image: cr.weaviate.io/semitechnologies/weaviate:1.32.0
+ image: cr.weaviate.io/semitechnologies/weaviate:1.33.0-dev-4d2ab70.arm64
ports:
- 8080:8080
- 50051:50051
diff --git a/tests/docker-compose-rbac.yml b/tests/docker-compose-rbac.yml
index 712a09b8..bc029512 100644
--- a/tests/docker-compose-rbac.yml
+++ b/tests/docker-compose-rbac.yml
@@ -1,4 +1,3 @@
----
services:
weaviate_rbac:
command:
@@ -8,11 +7,13 @@ services:
- '8080'
- --scheme
- http
- image: cr.weaviate.io/semitechnologies/weaviate:1.32.0
+ image: cr.weaviate.io/semitechnologies/weaviate:1.33.0-dev-4d2ab70.arm64
ports:
- 8580:8080
- 50551:50051
restart: on-failure:0
+ depends_on:
+ - keycloak
environment:
QUERY_DEFAULTS_LIMIT: 25
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
@@ -21,11 +22,44 @@ services:
ENABLE_API_BASED_MODULES: 'true'
BACKUP_FILESYSTEM_PATH: '/var/lib/weaviate/backups'
CLUSTER_HOSTNAME: 'node1'
- # AuthN and AuthZ settings
AUTHENTICATION_APIKEY_ENABLED: 'true'
AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'root-user-key'
AUTHENTICATION_APIKEY_USERS: 'root-user'
AUTHORIZATION_RBAC_ENABLED: 'true'
AUTHORIZATION_RBAC_ROOT_USERS: 'root-user'
AUTHENTICATION_DB_USERS_ENABLED: 'true'
-...
+ AUTHENTICATION_OIDC_ENABLED: 'true'
+ # Changed to use service name instead of localhost
+ #AUTHENTICATION_OIDC_ISSUER: 'http://localhost:8081/realms/weaviate-test'
+ AUTHENTICATION_OIDC_ISSUER: 'http://keycloak:8081/realms/weaviate-test'
+ AUTHENTICATION_OIDC_USERNAME_CLAIM: 'preferred_username'
+ AUTHENTICATION_OIDC_GROUPS_CLAIM: 'groups'
+ AUTHENTICATION_OIDC_CLIENT_ID: 'weaviate'
+
+ keycloak:
+ image: quay.io/keycloak/keycloak:24.0.3
+ ports:
+ - "8081:8081"
+ environment:
+ KEYCLOAK_ADMIN: admin
+ KEYCLOAK_ADMIN_PASSWORD: admin
+ KC_HTTP_ENABLED: 'true'
+ KC_HTTP_PORT: '8081'
+ KC_HOSTNAME_STRICT: 'false'
+ KC_HOSTNAME_STRICT_HTTPS: 'false'
+ # Use localhost so it works from both inside and outside Docker
+ #KC_HOSTNAME: localhost
+ KC_HOSTNAME_PORT: 8081
+ # This makes Keycloak use localhost URLs in OIDC discovery
+ KC_FRONTEND_URL: 'http://localhost:8081'
+ command:
+ - start-dev
+ volumes:
+ - keycloak_data:/opt/keycloak/data
+ # Remove health check for now since Keycloak is working
+ # healthcheck:
+ # test: ["CMD", "echo", "healthy"]
+ # interval: 10s
+
+volumes:
+ keycloak_data:
\ No newline at end of file
From a639a846189f4e51aa0b3f794bd6fe3de6951626 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 12:50:07 +0200
Subject: [PATCH 07/44] Update docs
---
.../howto.configure.rbac.oidc.groups.py | 631 +++++++-----------
.../configuration/rbac/manage-groups.mdx | 252 +++++++
sidebars.js | 1 +
3 files changed, 508 insertions(+), 376 deletions(-)
create mode 100644 docs/weaviate/configuration/rbac/manage-groups.mdx
diff --git a/_includes/code/python/howto.configure.rbac.oidc.groups.py b/_includes/code/python/howto.configure.rbac.oidc.groups.py
index b1dea599..d93c8b72 100644
--- a/_includes/code/python/howto.configure.rbac.oidc.groups.py
+++ b/_includes/code/python/howto.configure.rbac.oidc.groups.py
@@ -5,68 +5,75 @@
"""
import requests
-import json
import sys
from typing import Dict, Any, Optional
import weaviate
from weaviate.classes.init import Auth
from weaviate.classes.rbac import Permissions
+
def test_keycloak_connection(keycloak_ports: list = [8081]) -> Optional[str]:
"""Test if Keycloak is accessible on common ports"""
# Try keycloak hostname first (requires /etc/hosts mapping), then localhost
keycloak_configs = [
("keycloak", 8081), # This should match Weaviate's expected issuer
- ("localhost", 8081) # Fallback for initial testing
+ ("localhost", 8081), # Fallback for initial testing
]
-
+
for host, port in keycloak_configs:
keycloak_url = f"http://{host}:{port}"
try:
# First check if Keycloak is responding at all
response = requests.get(f"{keycloak_url}", timeout=5)
if response.status_code == 200:
- print(f"✅ Keycloak server found at {keycloak_url}")
-
+ print(f"OK: Keycloak server found at {keycloak_url}")
+
# Check if master realm exists (always exists)
- master_response = requests.get(f"{keycloak_url}/realms/master", timeout=5)
+ master_response = requests.get(
+ f"{keycloak_url}/realms/master", timeout=5
+ )
if master_response.status_code == 200:
- print(f"✅ Keycloak realms accessible")
-
+ print(f"OK: Keycloak realms accessible")
+
# Check if our test realm exists
- test_response = requests.get(f"{keycloak_url}/realms/weaviate-test", timeout=5)
+ test_response = requests.get(
+ f"{keycloak_url}/realms/weaviate-test", timeout=5
+ )
if test_response.status_code == 200:
- print(f"✅ weaviate-test realm found")
- print(f"✅ weaviate-test realm accessible")
+ print(f"OK: weaviate-test realm found")
+ print(f"OK: weaviate-test realm accessible")
return keycloak_url
else:
- print(f"⚠️ weaviate-test realm not found - you'll need to create it")
+ print(
+ f"Warning: weaviate-test realm not found - you'll need to create it"
+ )
return keycloak_url
except Exception as e:
print(f"Testing {keycloak_url}: {e}")
continue
-
- print(f"❌ Cannot connect to Keycloak")
- print("💡 Make sure you have '127.0.0.1 keycloak' in /etc/hosts")
- print("💡 Run: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts")
+
+ print(f"Error: Cannot connect to Keycloak")
+ print("Hint: Make sure you have '127.0.0.1 keycloak' in /etc/hosts")
+ print("Hint: Run: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts")
return None
+
def get_client_secret_instructions():
"""Print instructions for getting client secret"""
- print("\n" + "="*60)
- print("📋 KEYCLOAK SETUP INSTRUCTIONS")
- print("="*60)
+ print("\n" + "=" * 60)
+ print("KEYCLOAK SETUP INSTRUCTIONS")
+ print("=" * 60)
print("Your Keycloak is running! Now you need to set it up:")
print("")
- print("1. 🌐 Go to http://keycloak:8081 (make sure you have keycloak in /etc/hosts)")
- print("2. 🔑 Login with username: admin, password: admin")
- print("3. 🏛️ CREATE REALM:")
+ print("1. Go to http://keycloak:8081 (make sure you have keycloak in /etc/hosts)")
+ print("2. Login with username: admin, password: admin")
+ print("3. CREATE REALM:")
print(" - Click dropdown next to 'master' (top-left)")
print(" - Click 'Create Realm'")
print(" - Realm name: weaviate-test")
print(" - Click 'Create'")
print("")
- print("4. 📱 CREATE CLIENT:")
+ print("4. CREATE CLIENT:")
print(" - Go to 'Clients' → 'Create client'")
print(" - Client ID: weaviate")
print(" - Client type: OpenID Connect")
@@ -75,426 +82,298 @@ def get_client_secret_instructions():
print(" - Enable 'Direct access grants'")
print(" - Click 'Save'")
print("")
- print("5. 🔐 GET CLIENT SECRET:")
+ print("5. GET CLIENT SECRET:")
print(" - Go to 'Credentials' tab")
print(" - Copy the 'Client secret' value")
print("")
- print("6. 👥 CREATE GROUPS:")
+ print("6. CREATE GROUPS:")
print(" - Go to 'Groups'")
print(" - Create: /admin-group, /viewer-group, /my-test-group")
print("")
- print("7. 👤 CREATE USERS:")
+ print("7. CREATE USERS:")
print(" - Go to 'Users' → 'Create new user'")
print(" - Username: test-admin, set password: password123")
print(" - Add to groups: /admin-group, /my-test-group")
print(" - Create test-viewer user, add to /viewer-group")
print("")
- print("8. ⚙️ CONFIGURE GROUP CLAIMS:")
- print(" - Go to 'Client scopes' → 'weaviate-dedicated'")
- print(" - Add mapper → Group Membership")
- print(" - Name: groups, Token Claim Name: groups")
- print(" - Add to ID token: ON, Add to access token: ON")
- print("="*60)
+ print("8. CONFIGURE GROUP & AUDIENCE CLAIMS:")
+ print(" - Go to the 'weaviate' client -> 'Client scopes' -> 'weaviate-dedicated'")
+ print(" - Add mapper -> Group Membership & Audience")
+ print("=" * 60)
+
def get_oidc_token(
- keycloak_url: str = "http://keycloak:8081", # Changed default to keycloak hostname
- realm: str = "weaviate-test",
+ keycloak_url: str,
+ client_secret: str,
+ username: str,
+ password: str = "password123",
+ realm: str = "weaviate-test",
client_id: str = "weaviate",
- client_secret: str = "",
- username: str = "test-admin",
- password: str = "password123"
) -> Optional[str]:
"""Get OIDC token from Keycloak for a user"""
token_url = f"{keycloak_url}/realms/{realm}/protocol/openid-connect/token"
-
+
data = {
"grant_type": "password",
"client_id": client_id,
"client_secret": client_secret,
"username": username,
- "password": password
+ "password": password,
}
-
+
try:
response = requests.post(token_url, data=data, timeout=10)
-
+
if response.status_code == 200:
token_data = response.json()
- print(f"✅ Successfully got token for user: {username}")
+ print(f"OK: Successfully got token for user: {username}")
return token_data["access_token"]
else:
- print(f"❌ Failed to get token for {username}: {response.status_code}")
+ print(f"Error: Failed to get token for {username}: {response.status_code}")
if response.status_code == 401:
print(" → Check username/password or client secret")
elif response.status_code == 400:
print(" → Check client configuration (Direct Access Grants enabled?)")
print(f" → Response: {response.text}")
return None
-
- except Exception as e:
- print(f"❌ Error getting token for {username}: {e}")
- return None
-def decode_token_groups(token: str) -> Dict[str, Any]:
- """Decode JWT token to see groups (for debugging)"""
- try:
- import jwt
- decoded = jwt.decode(token, options={"verify_signature": False})
- return decoded
- except ImportError:
- print("⚠️ Install PyJWT to see token details: pip install PyJWT")
- return {}
- except Exception as e:
- print(f"⚠️ Error decoding token: {e}")
- return {}
-
-def show_token_info(token: str, username: str):
- """Display token information"""
- decoded = decode_token_groups(token)
- if decoded:
- print(f" → Username: {decoded.get('preferred_username', 'N/A')}")
- print(f" → Groups: {decoded.get('groups', [])}")
- print(f" → Issuer: {decoded.get('iss', 'N/A')}")
- print(f" → Realm roles: {decoded.get('realm_access', {}).get('roles', [])}")
-
-def run_automated_setup(keycloak_url: str) -> Optional[str]:
- """Run automated Keycloak setup using Admin API"""
- try:
- # Import the automated setup class inline
- import requests
- from typing import Optional, Dict
-
- class KeycloakSetup:
- def __init__(self, keycloak_url: str = "http://keycloak:8081", admin_user: str = "admin", admin_pass: str = "admin"):
- self.keycloak_url = keycloak_url.rstrip("/")
- self.admin_user = admin_user
- self.admin_pass = admin_pass
- self.admin_token = None
- self.realm_name = "weaviate-test"
- self.client_id = "weaviate"
-
- def get_admin_token(self) -> Optional[str]:
- token_url = f"{self.keycloak_url}/realms/master/protocol/openid-connect/token"
- data = {
- "grant_type": "password",
- "client_id": "admin-cli",
- "username": self.admin_user,
- "password": self.admin_pass,
- }
- try:
- response = requests.post(token_url, data=data, timeout=10)
- if response.status_code == 200:
- self.admin_token = response.json()["access_token"]
- return self.admin_token
- return None
- except Exception:
- return None
-
- def make_admin_request(self, method: str, endpoint: str, json_data: Dict = None) -> requests.Response:
- headers = {
- "Authorization": f"Bearer {self.admin_token}",
- "Content-Type": "application/json",
- }
- url = f"{self.keycloak_url}/admin/realms{endpoint}"
- if method.upper() == "GET":
- return requests.get(url, headers=headers, timeout=10)
- elif method.upper() == "POST":
- return requests.post(url, headers=headers, json=json_data, timeout=10)
-
- def create_realm(self) -> bool:
- response = self.make_admin_request("GET", f"/{self.realm_name}")
- if response.status_code == 200:
- return True
- realm_config = {"realm": self.realm_name, "enabled": True}
- response = self.make_admin_request("POST", "", realm_config)
- return response.status_code == 201
-
- def create_client(self) -> Optional[str]:
- client_config = {
- "clientId": self.client_id,
- "enabled": True,
- "clientAuthenticatorType": "client-secret",
- "secret": "weaviate-client-secret-123",
- "redirectUris": ["*"],
- "standardFlowEnabled": True,
- "directAccessGrantsEnabled": True,
- "publicClient": False,
- }
- response = self.make_admin_request("POST", f"/{self.realm_name}/clients", client_config)
- if response.status_code == 201:
- return "weaviate-client-secret-123"
- return None
-
- def setup_all(self) -> Optional[str]:
- if not self.get_admin_token():
- return None
- if not self.create_realm():
- return None
- return self.create_client()
-
- print("🤖 Running automated Keycloak setup...")
- setup = KeycloakSetup(keycloak_url)
- client_secret = setup.setup_all()
-
- if client_secret:
- print(f"\n🎉 Automated setup completed successfully!")
- return client_secret
- else:
- print("❌ Automated setup failed")
- return None
except Exception as e:
- print(f"❌ Automated setup error: {e}")
+ print(f"Error: Error getting token for {username}: {e}")
return None
+
def setup_and_validate_oidc() -> tuple[Optional[str], Optional[str]]:
"""Setup and validate OIDC connection, return (client_secret, keycloak_url) if successful"""
- print("🧪 KEYCLOAK OIDC SETUP VALIDATOR")
+ print("KEYCLOAK OIDC SETUP VALIDATOR")
print("=" * 50)
-
+
# Test Keycloak connection
print("Testing Keycloak connection...")
keycloak_url = test_keycloak_connection([8081])
if not keycloak_url:
- print("❌ Keycloak not accessible!")
+ print("Error: Keycloak not accessible!")
print("\nTroubleshooting:")
- print("1. Add keycloak to /etc/hosts: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts")
+ print(
+ "1. Add keycloak to /etc/hosts: echo '127.0.0.1 keycloak' | sudo tee -a /etc/hosts"
+ )
print("2. Check if docker-compose is running: docker-compose ps")
print("3. Check Keycloak logs: docker-compose logs keycloak")
return None, None
-
+
# Check if weaviate-test realm exists
try:
realm_response = requests.get(f"{keycloak_url}/realms/weaviate-test", timeout=5)
realm_exists = realm_response.status_code == 200
except:
realm_exists = False
-
+
if not realm_exists:
- print(f"\n⚠️ The 'weaviate-test' realm doesn't exist yet.")
- print("Choose your setup method:")
- print("1. 🤖 Automated setup (recommended)")
- print("2. 📋 Manual setup instructions")
-
- choice = input("\nEnter choice (1 or 2): ").strip()
-
- if choice == "1":
- client_secret = run_automated_setup(keycloak_url)
- if not client_secret:
- return None, None
- else:
- get_client_secret_instructions()
- setup_choice = input("\nHave you completed the manual setup? (y/n): ").strip().lower()
- if setup_choice != 'y':
- print("Please complete the Keycloak setup first, then run this script again.")
- return None, None
- client_secret = input("Enter Keycloak client secret: ").strip()
- if not client_secret:
- print("❌ Client secret required.")
- return None, None
- else:
- print(f"✅ weaviate-test realm accessible")
- print("\n" + "-"*30)
- client_secret = input("Enter Keycloak client secret (or 'auto' for automated setup): ").strip()
-
- if client_secret.lower() == 'auto':
- client_secret = run_automated_setup(keycloak_url)
- if not client_secret:
- return None, None
- elif not client_secret:
- print("❌ Client secret required.")
+ print(f"\nWarning: The 'weaviate-test' realm doesn't exist yet.")
+ print("Manual setup instructions")
+
+ get_client_secret_instructions()
+ setup_choice = (
+ input("\nHave you completed the manual setup? (y/n): ").strip().lower()
+ )
+ if setup_choice != "y":
+ print(
+ "Please complete the Keycloak setup first, then run this script again."
+ )
return None, None
-
+ client_secret = input("Enter Keycloak client secret: ").strip()
+ if not client_secret:
+ print("Error: Client secret required.")
+ return None, None
+ else:
+ print(f"OK: weaviate-test realm accessible")
+ print("\n" + "-" * 30)
+ # Using a fixed secret for automated testing
+ client_secret = "weaviate-client-secret-123"
+ print(f"Using client secret: {client_secret}")
+
# Test tokens with the keycloak_url (which should be http://keycloak:8081)
- print(f"\n🔑 Testing OIDC tokens...")
- admin_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin")
-
+ print(f"\nTesting OIDC tokens...")
+ admin_token = get_oidc_token(
+ keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin"
+ )
+
if not admin_token:
- print("\n❌ Cannot get admin token. Please verify:")
+ print("\nError: Cannot get admin token. Please verify:")
print("- User 'test-admin' exists with password 'password123'")
print("- User is in groups like '/admin-group'")
print("- Client 'weaviate' has 'Direct access grants' enabled")
print("- Client secret is correct")
return None, None
-
- show_token_info(admin_token, "test-admin")
-
- viewer_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer")
- if viewer_token:
- show_token_info(viewer_token, "test-viewer")
- else:
- print("⚠️ Viewer token failed, but continuing with admin token")
-
- print("\n✅ OIDC setup validated successfully!")
- return client_secret, keycloak_url
-def main():
- """Main function to run OIDC group management tests"""
-
- # Setup and validate OIDC first
- client_secret, keycloak_url = setup_and_validate_oidc()
- if not client_secret or not keycloak_url:
- sys.exit(1)
-
- print("\n" + "="*60)
- print("🚀 STARTING OIDC GROUP MANAGEMENT TESTS")
- print("="*60)
-
- # START AdminClient
- # Connect to Weaviate as root user (for admin operations)
- admin_client = weaviate.connect_to_local(
- port=8580,
- grpc_port=50551,
- auth_credentials=Auth.api_key("root-user-key"),
+ viewer_token = get_oidc_token(
+ keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer"
)
- # END AdminClient
-
- # Create test roles for group management
- print("\n📋 Setting up test roles...")
- permissions = [
- Permissions.collections(
- collection="TargetCollection*", read_config=True, create_collection=True
- ),
- Permissions.data(collection="TargetCollection*", read=True, create=True),
- ]
+ if not viewer_token:
+ print("Warning: Viewer token failed, but continuing with admin token")
- admin_client.roles.delete(role_name="testRole")
- admin_client.roles.create(role_name="testRole", permissions=permissions)
-
- admin_client.roles.delete(role_name="groupViewerRole")
- admin_client.roles.create(role_name="groupViewerRole", permissions=[
- Permissions.data(collection="*", read=True)
- ])
-
- print("\n🔧 ADMIN OPERATIONS (Using API Key)")
- print("-" * 40)
-
- # START AssignOidcGroupRoles
- admin_client.groups.oidc.assign_roles(group_id="/admin-group", role_names=["testRole", "viewer"])
- admin_client.groups.oidc.assign_roles(group_id="/viewer-group", role_names=["viewer"])
- admin_client.groups.oidc.assign_roles(group_id="/my-test-group", role_names=["groupViewerRole"])
- print("✅ Assigned roles to OIDC groups")
- # END AssignOidcGroupRoles
-
- # START GetKnownOidcGroups
- known_groups = admin_client.groups.oidc.get_known_group_names()
- print(f"📁 Known OIDC groups ({len(known_groups)}):")
- for group in known_groups:
- print(f" - {group}")
- # END GetKnownOidcGroups
-
- # START GetGroupAssignments
- group_assignments = admin_client.roles.get_group_assignments(role_name="testRole")
- print(f"👥 Groups assigned to role 'testRole':")
- for group in group_assignments:
- print(f" - Group ID: {group.group_id}")
- print(f" Group Type: {group.group_type}")
- # END GetGroupAssignments
-
- admin_client.close()
-
- print(f"\n👤 OIDC USER OPERATIONS")
- print("-" * 40)
-
- # Get tokens for different users using keycloak_url
- # START GetOidcToken
- admin_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin")
- viewer_token = get_oidc_token(keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer")
- # END GetOidcToken
-
- if admin_token:
- # START OidcAdminClient
- # Connect as OIDC admin user
- oidc_admin_client = weaviate.connect_to_local(
- port=8580,
- grpc_port=50551,
- auth_credentials=Auth.bearer_token(admin_token),
- )
- # END OidcAdminClient
-
- try:
- # START GetCurrentUserRoles
- my_user = oidc_admin_client.users.get_my_user()
- current_roles = my_user.roles if my_user else []
- print(f"🔑 Admin user's current roles ({len(current_roles)}):")
- for role in current_roles:
- print(f" - {role}")
- # END GetCurrentUserRoles
-
- # Test admin can see group assignments (if they have permissions)
- try:
- # START GetOidcGroupRoles
- group_roles = oidc_admin_client.groups.oidc.get_assigned_roles(
- group_id="/admin-group",
- include_permissions=True
- )
- print(f"👑 Admin group roles:")
- for role_name, role_obj in group_roles.items():
- print(f" - {role_name}")
- # END GetOidcGroupRoles
- except Exception as e:
- print(f"⚠️ Admin user cannot access group details: {e}")
-
- except Exception as e:
- print(f"❌ Error with admin OIDC operations: {e}")
- finally:
- oidc_admin_client.close()
-
- if viewer_token:
- # START OidcViewerClient
- # Connect as OIDC viewer user
- oidc_viewer_client = weaviate.connect_to_local(
- port=8580,
- grpc_port=50551,
- auth_credentials=Auth.bearer_token(viewer_token),
- )
- # END OidcViewerClient
-
- try:
- # START GetCurrentUserRolesViewer
- my_user = oidc_viewer_client.users.get_my_user()
- current_roles = my_user.roles if my_user else []
- print(f"👀 Viewer user's current roles ({len(current_roles)}):")
- for role in current_roles:
- print(f" - {role}")
- # END GetCurrentUserRolesViewer
-
- # Viewer should have limited permissions
- try:
- viewer_groups = oidc_viewer_client.groups.oidc.get_known_group_names()
- print(f"👀 Viewer can see groups: {viewer_groups}")
- except Exception as e:
- print(f"⚠️ Viewer user cannot access group operations: {e}")
-
- except Exception as e:
- print(f"❌ Error with viewer OIDC operations: {e}")
- finally:
- oidc_viewer_client.close()
-
- print(f"\n🧹 CLEANUP (Admin operations)")
- print("-" * 40)
-
- # Reconnect as admin for cleanup
- admin_client = weaviate.connect_to_local(
- port=8580,
- grpc_port=50551,
- auth_credentials=Auth.api_key("root-user-key"),
- )
-
- # START RevokeOidcGroupRoles
- admin_client.groups.oidc.revoke_roles(group_id="/admin-group", role_names=["testRole", "viewer"])
- admin_client.groups.oidc.revoke_roles(group_id="/viewer-group", role_names=["viewer"])
- admin_client.groups.oidc.revoke_roles(group_id="/my-test-group", role_names=["groupViewerRole"])
- print("✅ Revoked all assigned group roles")
- # END RevokeOidcGroupRoles
-
- # Verify cleanup
- final_groups = admin_client.groups.oidc.get_known_group_names()
- print(f"📁 Remaining known groups after cleanup: {final_groups}")
-
- admin_client.close()
+ print("\nOK: OIDC setup validated successfully!")
+ return client_secret, keycloak_url
- print(f"\n🎉 OIDC GROUP MANAGEMENT TESTING COMPLETE!")
- print("="*60)
-if __name__ == "__main__":
- main()
\ No newline at end of file
+# Setup and validate OIDC first
+client_secret, keycloak_url = setup_and_validate_oidc()
+if not client_secret or not keycloak_url:
+ sys.exit(1)
+
+print("\n" + "=" * 60)
+print("STARTING OIDC GROUP MANAGEMENT TESTS")
+print("=" * 60)
+
+# The admin_client is used for setup and cleanup that requires root privileges
+admin_client = None
+
+# START AdminClient
+# Connect to Weaviate as root user (for admin operations)
+admin_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.api_key("root-user-key"),
+)
+# END AdminClient
+
+# Create test roles for group management
+print("\nSetting up test roles...")
+permissions = [
+ Permissions.collections(
+ collection="TargetCollection*", read_config=True, create_collection=True
+ ),
+ Permissions.data(collection="TargetCollection*", read=True, create=True),
+]
+
+admin_client.roles.delete(role_name="testRole")
+admin_client.roles.create(role_name="testRole", permissions=permissions)
+
+admin_client.roles.delete(role_name="groupViewerRole")
+admin_client.roles.create(
+ role_name="groupViewerRole",
+ permissions=[Permissions.data(collection="*", read=True)],
+)
+
+print("\nADMIN OPERATIONS (Using API Key)")
+print("-" * 40)
+
+# START AssignOidcGroupRoles
+admin_client.groups.oidc.assign_roles(
+ group_id="/admin-group", role_names=["testRole", "viewer"]
+)
+# END AssignOidcGroupRoles
+admin_client.groups.oidc.assign_roles(group_id="/viewer-group", role_names=["viewer"])
+admin_client.groups.oidc.assign_roles(
+ group_id="/my-test-group", role_names=["groupViewerRole"]
+)
+
+# START GetKnownOidcGroups
+known_groups = admin_client.groups.oidc.get_known_group_names()
+print(f"Known OIDC groups ({len(known_groups)}): {known_groups}")
+# END GetKnownOidcGroups
+assert len(known_groups) == 3
+assert set(known_groups) == {"/admin-group", "/viewer-group", "/my-test-group"}
+
+# START GetGroupAssignments
+group_assignments = admin_client.roles.get_group_assignments(role_name="testRole")
+print(f"Groups assigned to role 'testRole':")
+for group in group_assignments:
+ print(f" - Group ID: {group.group_id}, Type: {group.group_type}")
+# END GetGroupAssignments
+assert len(group_assignments) == 1
+assert group_assignments[0].group_id == "/admin-group"
+
+print(f"\nOIDC USER OPERATIONS")
+print("-" * 40)
+
+# Get tokens for different users using keycloak_url
+# START GetOidcToken
+admin_token = get_oidc_token(
+ keycloak_url=keycloak_url, client_secret=client_secret, username="test-admin"
+)
+viewer_token = get_oidc_token(
+ keycloak_url=keycloak_url, client_secret=client_secret, username="test-viewer"
+)
+# END GetOidcToken
+assert admin_token is not None
+assert viewer_token is not None
+
+# --- Admin User Tests ---
+# START OidcAdminClient
+# Connect as OIDC admin user
+oidc_admin_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.bearer_token(admin_token),
+)
+# END OidcAdminClient
+
+# START GetCurrentUserRoles
+my_user = oidc_admin_client.users.get_my_user()
+current_roles_dict = my_user.roles if my_user else []
+role_names = list(current_roles_dict.keys())
+print(f"Admin user's current roles ({len(role_names)}): {role_names}")
+# END GetCurrentUserRoles
+assert set(role_names) == {"viewer", "testRole", "groupViewerRole"}
+
+# START GetOidcGroupRoles
+group_roles = oidc_admin_client.groups.oidc.get_assigned_roles(
+ group_id="/admin-group", include_permissions=True
+)
+print(f"Roles assigned to '/admin-group': {list(group_roles.keys())}")
+# END GetOidcGroupRoles
+assert set(group_roles.keys()) == {"testRole", "viewer"}
+oidc_admin_client.close()
+
+# --- Viewer User Tests ---
+# START OidcViewerClient
+# Connect as OIDC viewer user
+oidc_viewer_client = weaviate.connect_to_local(
+ port=8580,
+ grpc_port=50551,
+ auth_credentials=Auth.bearer_token(viewer_token),
+)
+# END OidcViewerClient
+
+# START GetCurrentUserRolesViewer
+my_user = oidc_viewer_client.users.get_my_user()
+current_roles_dict = my_user.roles if my_user else {}
+role_names = list(current_roles_dict.keys())
+print(f"Viewer user's current roles ({len(role_names)}): {role_names}")
+# END GetCurrentUserRolesViewer
+assert role_names == ["viewer"]
+
+# Viewer should have limited permissions but can still see group names
+try:
+ viewer_groups = oidc_viewer_client.groups.oidc.get_known_group_names()
+ print(f"Viewer can see groups: {viewer_groups}")
+ assert set(viewer_groups) == {"/admin-group", "/viewer-group", "/my-test-group"}
+except Exception as e:
+ # This part should not be reached if permissions are set correctly
+ assert False, f"Viewer user failed to access group operations: {e}"
+
+oidc_viewer_client.close()
+
+print(f"\nCLEANUP (Admin operations)")
+print("-" * 40)
+
+# START RevokeOidcGroupRoles
+admin_client.groups.oidc.revoke_roles(
+ group_id="/admin-group", role_names=["testRole", "viewer"]
+)
+# END RevokeOidcGroupRoles
+admin_client.groups.oidc.revoke_roles(group_id="/viewer-group", role_names=["viewer"])
+admin_client.groups.oidc.revoke_roles(
+ group_id="/my-test-group", role_names=["groupViewerRole"]
+)
+
+# Verify cleanup
+final_groups = admin_client.groups.oidc.get_known_group_names()
+print(f"Remaining known groups after cleanup: {final_groups}")
+assert len(final_groups) == 0
+
+admin_client.close()
+
+print("\n" + "=" * 60)
+print("OIDC GROUP MANAGEMENT TESTING COMPLETE!")
+print("=" * 60)
diff --git a/docs/weaviate/configuration/rbac/manage-groups.mdx b/docs/weaviate/configuration/rbac/manage-groups.mdx
new file mode 100644
index 00000000..a1300638
--- /dev/null
+++ b/docs/weaviate/configuration/rbac/manage-groups.mdx
@@ -0,0 +1,252 @@
+---
+title: Manage groups
+sidebar_label: Manage groups
+image: og/docs/configuration.jpg
+# tags: ['rbac', 'groups', 'configuration', 'authorization', 'oidc']
+---
+
+import Link from "@docusaurus/Link";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import FilteredTextBlock from "@site/src/components/Documentation/FilteredTextBlock";
+import OidcGroupPyCode from "!!raw-loader!/_includes/code/python/howto.configure.rbac.oidc.groups.py";
+
+
+:::info Added in `v1.33`
+:::
+
+When using [OIDC](/deploy/configuration/oidc.md) for authentication, you can leverage user groups defined in your identity provider (like Keycloak, Okta, or Auth0) to manage permissions in Weaviate. The user's group memberships are passed to Weaviate in the OIDC token.
+
+You can then assign Weaviate roles directly to these **OIDC groups**. Any user who is a member of that group will automatically inherit the permissions of the assigned roles. This is a powerful way to manage access for large teams without assigning roles to each user individually.
+
+On this page, you will find examples of how to programmatically **manage OIDC groups** and their associated roles.
+
+## Group management {#group-management}
+
+### Assign roles to an OIDC group
+
+You can assign one or more Weaviate roles to an OIDC group. Any user belonging to this group will inherit the roles' permissions.
+
+This example assigns the `testRole` and `viewer` roles to the `/admin-group`.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+### Revoke roles from an OIDC group
+
+You can revoke one or more roles from a specific OIDC group.
+
+This example removes the `testRole` and `viewer` roles from the `/admin-group`.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+### List roles assigned to an OIDC group
+
+Retrieve a list of all roles that have been assigned to a specific OIDC group.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+
+Example results
+
+```text
+Roles assigned to '/admin-group': ['testRole', 'viewer']
+```
+
+
+
+### List all known OIDC groups
+
+This example shows how to get a list of all OIDC groups that Weaviate is aware of. Weaviate learns about a group when a role is first assigned to it.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+
+Example results
+
+```text
+Known OIDC groups (3): ['/viewer-group', '/admin-group', '/my-test-group']
+```
+
+
+
+### List groups assigned to a role
+
+Retrieve a list of all groups that have been assigned a specific role.
+
+This example shows which groups have the `testRole` assigned to them.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+
+Example results
+
+```text
+Groups assigned to role 'testRole':
+ - Group ID: /admin-group, Type: oidc
+```
+
+
+
+## Further resources
+
+- [RBAC: Overview](https://www.google.com/search?q=./index.mdx)
+- [RBAC: Configuration](https://www.google.com/search?q=/deploy/configuration/configuring-rbac.md)
+- [RBAC: Manage roles](https://www.google.com/search?q=./manage-roles.mdx)
+- [RBAC: Manage users](https://www.google.com/search?q=./manage-users.mdx)
+
+## Questions and feedback
+
+import DocsFeedback from "/_includes/docs-feedback.mdx";
+
+
+````
diff --git a/sidebars.js b/sidebars.js
index 30203c35..9a5f7075 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -450,6 +450,7 @@ const sidebars = {
items: [
"weaviate/configuration/rbac/manage-roles",
"weaviate/configuration/rbac/manage-users",
+ "weaviate/configuration/rbac/manage-groups",
],
},
],
From b20fe4ecc30a92c308d50b6caf158a2c2ff3154d Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:31:50 +0200
Subject: [PATCH 08/44] Update docs
---
.../howto.configure.rbac.oidc.groups.py | 64 ++-----------------
1 file changed, 5 insertions(+), 59 deletions(-)
diff --git a/_includes/code/python/howto.configure.rbac.oidc.groups.py b/_includes/code/python/howto.configure.rbac.oidc.groups.py
index d93c8b72..19d23433 100644
--- a/_includes/code/python/howto.configure.rbac.oidc.groups.py
+++ b/_includes/code/python/howto.configure.rbac.oidc.groups.py
@@ -6,7 +6,7 @@
import requests
import sys
-from typing import Dict, Any, Optional
+from typing import Optional
import weaviate
from weaviate.classes.init import Auth
from weaviate.classes.rbac import Permissions
@@ -58,50 +58,6 @@ def test_keycloak_connection(keycloak_ports: list = [8081]) -> Optional[str]:
return None
-def get_client_secret_instructions():
- """Print instructions for getting client secret"""
- print("\n" + "=" * 60)
- print("KEYCLOAK SETUP INSTRUCTIONS")
- print("=" * 60)
- print("Your Keycloak is running! Now you need to set it up:")
- print("")
- print("1. Go to http://keycloak:8081 (make sure you have keycloak in /etc/hosts)")
- print("2. Login with username: admin, password: admin")
- print("3. CREATE REALM:")
- print(" - Click dropdown next to 'master' (top-left)")
- print(" - Click 'Create Realm'")
- print(" - Realm name: weaviate-test")
- print(" - Click 'Create'")
- print("")
- print("4. CREATE CLIENT:")
- print(" - Go to 'Clients' → 'Create client'")
- print(" - Client ID: weaviate")
- print(" - Client type: OpenID Connect")
- print(" - Click 'Next'")
- print(" - Enable 'Client authentication'")
- print(" - Enable 'Direct access grants'")
- print(" - Click 'Save'")
- print("")
- print("5. GET CLIENT SECRET:")
- print(" - Go to 'Credentials' tab")
- print(" - Copy the 'Client secret' value")
- print("")
- print("6. CREATE GROUPS:")
- print(" - Go to 'Groups'")
- print(" - Create: /admin-group, /viewer-group, /my-test-group")
- print("")
- print("7. CREATE USERS:")
- print(" - Go to 'Users' → 'Create new user'")
- print(" - Username: test-admin, set password: password123")
- print(" - Add to groups: /admin-group, /my-test-group")
- print(" - Create test-viewer user, add to /viewer-group")
- print("")
- print("8. CONFIGURE GROUP & AUDIENCE CLAIMS:")
- print(" - Go to the 'weaviate' client -> 'Client scopes' -> 'weaviate-dedicated'")
- print(" - Add mapper -> Group Membership & Audience")
- print("=" * 60)
-
-
def get_oidc_token(
keycloak_url: str,
client_secret: str,
@@ -169,21 +125,11 @@ def setup_and_validate_oidc() -> tuple[Optional[str], Optional[str]]:
if not realm_exists:
print(f"\nWarning: The 'weaviate-test' realm doesn't exist yet.")
- print("Manual setup instructions")
-
- get_client_secret_instructions()
- setup_choice = (
- input("\nHave you completed the manual setup? (y/n): ").strip().lower()
+ print(
+ "Please complete the Keycloak setup first with keycloak_helper_script.py, then run this script again."
)
- if setup_choice != "y":
- print(
- "Please complete the Keycloak setup first, then run this script again."
- )
- return None, None
- client_secret = input("Enter Keycloak client secret: ").strip()
- if not client_secret:
- print("Error: Client secret required.")
- return None, None
+ return None, None
+
else:
print(f"OK: weaviate-test realm accessible")
print("\n" + "-" * 30)
From 59f6244f87b1f1c075784cca3ac6a42e50a9d406 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:41:12 +0200
Subject: [PATCH 09/44] Update docs
---
_includes/starter-guides/compression-types.mdx | 2 +-
docs/weaviate/concepts/vector-quantization.md | 6 ++++--
docs/weaviate/configuration/compression/rq-compression.md | 6 ++++--
3 files changed, 9 insertions(+), 5 deletions(-)
diff --git a/_includes/starter-guides/compression-types.mdx b/_includes/starter-guides/compression-types.mdx
index 4e6571fe..be2878f3 100644
--- a/_includes/starter-guides/compression-types.mdx
+++ b/_includes/starter-guides/compression-types.mdx
@@ -4,6 +4,6 @@
You control the number of segments, segment granularity, and the size of the training set.
- [Scalar Quantization (SQ)](/weaviate/configuration/compression/sq-compression) SQ reduces the size of each vector dimension from 32 bits to 8 bits. SQ trains on your data to create custom buckets for each dimension. This training helps SQ to preserve data characteristics when it maps information from the 32 bit dimensions into 8 bit buckets.
-- [Rotational Quantization (RQ)](/weaviate/configuration/compression/rq-compression) RQ reduces the size of each vector dimension from 32 bits to 8 bits without requiring training. RQ first applies a fast pseudorandom rotation to the vector, then quantizes each dimension to 8 bits. The rotation spreads information evenly across dimensions, enabling up to 98-99% recall without any configuration or training phase.
+- [Rotational Quantization (RQ)](/weaviate/configuration/compression/rq-compression) RQ reduces the size of each vector dimension from 32 bits to 8 bits (or 1 bit) without requiring training. RQ first applies a fast pseudorandom rotation to the vector, then quantizes each dimension. The rotation spreads information evenly across dimensions, enabling up to 98-99% recall without any configuration or training phase.
- [Binary Quantization (BQ)](/weaviate/configuration/compression/bq-compression) BQ reduces the size of each vector dimension to a single bit. This compression algorithm works best for vectors with high dimensionality.
diff --git a/docs/weaviate/concepts/vector-quantization.md b/docs/weaviate/concepts/vector-quantization.md
index 439cd945..3e7924b1 100644
--- a/docs/weaviate/concepts/vector-quantization.md
+++ b/docs/weaviate/concepts/vector-quantization.md
@@ -116,7 +116,9 @@ When SQ is enabled, Weaviate boosts recall by over-fetching compressed results.
:::caution Technical preview
-Rotational quantization (RQ) was added in **`v1.32`** as a **technical preview**.
+**8-bit Rotational quantization (RQ)** was added in **`v1.32`** as a **technical preview**.
+**1-bit Rotational quantization (RQ)** was added in **`v1.33`** as a **technical preview**.
+
This means that the feature is still under development and may change in future releases, including potential breaking changes.
**We do not recommend using this feature in production environments at this time.**
@@ -142,7 +144,7 @@ This means that the feature is still under development and may change in future
- **Data vectors**: Quantized using 1 bit per dimension by storing only the sign of each entry
- **Query vectors**: Scalar quantized using 5 bits per dimension during search
-This asymmetric approach improves recall compared to symmetric 1-bit schemes (such as BQ) by using more precision for query vectors during distance calculation. On datasets well-suited for BQ (like OpenAI embeddings), 1-bit RQ essentially matches BQ recall. It also works well on datasets where BQ performs poorly (such as [SIFT](https://arxiv.org/abs/2504.09081))
+This asymmetric approach improves recall compared to symmetric 1-bit schemes (such as BQ) by using more precision for query vectors during distance calculation. On datasets well-suited for BQ (like OpenAI embeddings), 1-bit RQ essentially matches BQ recall. It also works well on datasets where BQ performs poorly (such as [SIFT](https://arxiv.org/abs/2504.09081)).
### RQ characteristics
diff --git a/docs/weaviate/configuration/compression/rq-compression.md b/docs/weaviate/configuration/compression/rq-compression.md
index fda60947..df90ce65 100644
--- a/docs/weaviate/configuration/compression/rq-compression.md
+++ b/docs/weaviate/configuration/compression/rq-compression.md
@@ -15,13 +15,15 @@ import JavaCode from '!!raw-loader!/\_includes/code/howto/java/src/test/java/io/
:::caution Technical preview
-Rotational quantization (RQ) was added in **`v1.32`** as a **technical preview**.
+**8-bit Rotational quantization (RQ)** was added in **`v1.32`** as a **technical preview**.
+**1-bit Rotational quantization (RQ)** was added in **`v1.33`** as a **technical preview**.
+
This means that the feature is still under development and may change in future releases, including potential breaking changes.
**We do not recommend using this feature in production environments at this time.**
:::
-[**Rotational quantization (RQ)**](../../concepts/vector-quantization.md#rotational-quantization) is a fast untrained vector compression technique:
+[**Rotational quantization (RQ)**](../../concepts/vector-quantization.md#rotational-quantization) is a fast untrained vector compression technique. Two RQ variants are available in Weaviate:
- **8-bit RQ**: Up to 4x compression while retaining almost perfect recall (98-99% on most datasets).
- **1-bit RQ**: Close to 32x compression as dimensionality increases with moderate recall across various datasets.
From b72f6f6502bd83ccfea7655b2f5fe8d9f53c7b1d Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 14:50:50 +0200
Subject: [PATCH 10/44] Add new operators
---
_includes/code/howto/search.filters.py | 31 ++++++++++++++++
docs/weaviate/api/graphql/filters.md | 18 +++++++---
docs/weaviate/manage-objects/delete.mdx | 4 +--
docs/weaviate/search/filters.md | 47 +++++++++++++++++++++++--
4 files changed, 91 insertions(+), 9 deletions(-)
diff --git a/_includes/code/howto/search.filters.py b/_includes/code/howto/search.filters.py
index 34744326..84c2d43a 100644
--- a/_includes/code/howto/search.filters.py
+++ b/_includes/code/howto/search.filters.py
@@ -136,6 +136,37 @@
# End test
+# ==========================================
+# ===== ContainsNoneFilter =====
+# ==========================================
+
+# ContainsNoneFilter
+from weaviate.classes.query import Filter
+
+jeopardy = client.collections.get("JeopardyQuestion")
+
+# highlight-start
+token_list = ["blue", "red"]
+# highlight-end
+
+response = jeopardy.query.fetch_objects(
+ # highlight-start
+ # Find objects where the `question` property contains none of the strings in `token_list`
+ filters=Filter.by_property("question").contains_none(token_list),
+ # highlight-end
+ limit=3
+)
+
+for o in response.objects:
+ print(o.properties)
+# END ContainsNoneFilter
+
+# Test results
+assert response.objects[0].collection == "JeopardyQuestion"
+assert (token_list[0] not in response.objects[0].properties["question"].lower() and token_list[1] not in response.objects[0].properties["question"].lower())
+# End test
+
+
# ==========================================
# ===== Partial Match Filter =====
# ==========================================
diff --git a/docs/weaviate/api/graphql/filters.md b/docs/weaviate/api/graphql/filters.md
index 220b1138..2da35f1a 100644
--- a/docs/weaviate/api/graphql/filters.md
+++ b/docs/weaviate/api/graphql/filters.md
@@ -59,6 +59,7 @@ The `where` filter is an [algebraic object](https://en.wikipedia.org/wiki/Algebr
- `Operator` (which takes one of the following values)
- `And`
- `Or`
+ - `Not`
- `Equal`
- `NotEqual`
- `GreaterThan`
@@ -70,6 +71,7 @@ The `where` filter is an [algebraic object](https://en.wikipedia.org/wiki/Algebr
- `IsNull`
- `ContainsAny` (*Only for array and text properties)
- `ContainsAll` (*Only for array and text properties)
+ - `ContainsNone` (*Only for array and text properties)
- `Path`: Is a list of strings in [XPath](https://en.wikipedia.org/wiki/XPath#Abbreviated_syntax) style, indicating the property name of the collection.
- If the property is a cross-reference, the path should be followed as a list of strings. For a `inPublication` reference property that refers to `Publication` collection, the path selector for `name` will be `["inPublication", "Publication", "name"]`.
- `valueType`
@@ -239,15 +241,15 @@ Each `Like` filter iterates over the entire inverted index for that property. Th
Currently, the `Like` filter is not able to match wildcard characters (`?` and `*`) as literal characters. For example, it is currently not possible to only match the string `car*` and not `car`, `care` or `carpet`. This is a known limitation and may be addressed in future versions of Weaviate.
-### `ContainsAny` / `ContainsAll`
+### `ContainsAny` / `ContainsAll` / `ContainsNone`
-The `ContainsAny` and `ContainsAll` operators filter objects using values of an array as criteria.
+The `ContainsAny`, `ContainsAll` and `ContainsNone` operators filter objects using values of an array as criteria.
Both operators expect an array of values and return objects that match based on the input values.
-:::note `ContainsAny` and `ContainsAll` notes:
-- The `ContainsAny` and `ContainsAll` operators treat texts as an array. The text is split into an array of tokens based on the chosen tokenization scheme, and the search is performed on that array.
-- When using `ContainsAny` or `ContainsAll` with the REST api for [batch deletion](../../manage-objects/delete.mdx#delete-multiple-objects), the text array must be specified with the `valueTextArray` argument. This is different from the usage in search, where the `valueText` argument that can be used.
+:::note `ContainsAny`/`ContainsAll`/`ContainsNone` notes:
+- The `ContainsAny`, `ContainsAll` and `ContainsNone` operators treat texts as an array. The text is split into an array of tokens based on the chosen tokenization scheme, and the search is performed on that array.
+- When using `ContainsAny`, `ContainsAll` and `ContainsNone` with the REST api for [batch deletion](../../manage-objects/delete.mdx#delete-multiple-objects), the text array must be specified with the `valueTextArray` argument. This is different from the usage in search, where the `valueText` argument that can be used.
:::
@@ -265,6 +267,12 @@ A `ContainsAny` query on a path of `["languages_spoken"]` with a value of `["Chi
Using the same dataset of `Person` objects as above, a `ContainsAll` query on a path of `["languages_spoken"]` with a value of `["Chinese", "French", "English"]` will return objects where all three of those languages are present in the `languages_spoken` array.
+#### `ContainsNone`
+
+`ContainsNone` returns objects where none of the values from the input array are present.
+
+Using the same dataset of `Person` objects as above, a `ContainsNone` query on a path of `["languages_spoken"]` with a value of `["Chinese", "French", "English"]` will return objects where **none** of those languages are present in the `languages_spoken` array. For example, a person who speaks only Spanish would be returned, but a person who speaks English would be excluded.
+
## Filter performance
import RangeFilterPerformanceNote from '/_includes/range-filter-performance-note.mdx';
diff --git a/docs/weaviate/manage-objects/delete.mdx b/docs/weaviate/manage-objects/delete.mdx
index bc947eef..031949d6 100644
--- a/docs/weaviate/manage-objects/delete.mdx
+++ b/docs/weaviate/manage-objects/delete.mdx
@@ -192,9 +192,9 @@ To delete objects that match a set of criteria, specify the collection and a [`w
-### ContainsAny / ContainsAll
+### ContainsAny / ContainsAll / ContainsNone
-Use `ContainsAny` / `ContainsAll` filters to delete of objects by a set of criteria.
+Use `ContainsAny` / `ContainsAll` / `ContainsNone` filters to delete of objects by a set of criteria.
diff --git a/docs/weaviate/search/filters.md b/docs/weaviate/search/filters.md
index b89deb2c..41450ec8 100644
--- a/docs/weaviate/search/filters.md
+++ b/docs/weaviate/search/filters.md
@@ -515,9 +515,52 @@ The output is like this:
-## `ContainsAny` and `ContainsAll` with batch delete
+## `ContainsNone` Filter
-If you want to do a batch delete, see [Delete objects](../manage-objects/delete.mdx#containsany--containsall).
+The `ContainsNone` operator works on text properties and take an array of values as input. It will match objects where the property **contains none** of the values in the array.
+
+
+
+
+
+
+
+```typescript
+// TypeScript/JavaScript support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+
+ Example response
+
+The output is like this:
+
+
+
+## `ContainsAny`, `ContainsAll` and `ContainsNone` with batch delete
+
+If you want to do a batch delete, see [Delete objects](../manage-objects/delete.mdx#containsany--containsall--containsnone).
## Filter text on partial matches
From 13e0745c55a3963dbb0a6c4bcdb7b9d13b67821c Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Wed, 27 Aug 2025 17:08:40 +0200
Subject: [PATCH 11/44] Update docs
---
docs/weaviate/manage-objects/import.mdx | 2 +-
tests/docker-compose-anon.yml | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/weaviate/manage-objects/import.mdx b/docs/weaviate/manage-objects/import.mdx
index b0961a76..edcdf003 100644
--- a/docs/weaviate/manage-objects/import.mdx
+++ b/docs/weaviate/manage-objects/import.mdx
@@ -106,7 +106,7 @@ This means that the feature is still under development and may change in future
:::
-Here's how to import objects into a collection named `MyCollection`. The client will handle sending the data in optimal chunks.
+Here's how to import objects into a collection named `MyCollection` using [server-side batch imports](../concepts/data-import.mdx#server-side-batching). The client will handle sending the data in optimal chunks.
diff --git a/tests/docker-compose-anon.yml b/tests/docker-compose-anon.yml
index 4052eda7..ba8a7116 100644
--- a/tests/docker-compose-anon.yml
+++ b/tests/docker-compose-anon.yml
@@ -8,7 +8,7 @@ services:
- '8080'
- --scheme
- http
- image: cr.weaviate.io/semitechnologies/weaviate:1.32.0
+ image: cr.weaviate.io/semitechnologies/weaviate:1.33.0-rc.0-7f4e699.arm64@sha256:35def4b6e3a80f1b77c7a69715a09de47d2c17dd7c698da94b1d4835fd6b8561
ports:
- 8080:8080
- 50051:50051
From 7c0a09f2c3ba8f039a1dadb8cd2158e6662ab19b Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Thu, 28 Aug 2025 08:38:57 +0200
Subject: [PATCH 12/44] Update docs
---
.../python/howto.configure.rbac.oidc.users.py | 8 ++--
.../code/python/howto.configure.rbac.roles.py | 30 ++++++++++--
docs/weaviate/configuration/rbac/index.mdx | 25 ++++++++++
.../configuration/rbac/manage-roles.mdx | 46 ++++++++++++++++++-
tests/docker-compose-rbac.yml | 2 +-
5 files changed, 100 insertions(+), 11 deletions(-)
diff --git a/_includes/code/python/howto.configure.rbac.oidc.users.py b/_includes/code/python/howto.configure.rbac.oidc.users.py
index 03fcf75a..67499586 100644
--- a/_includes/code/python/howto.configure.rbac.oidc.users.py
+++ b/_includes/code/python/howto.configure.rbac.oidc.users.py
@@ -31,11 +31,11 @@
# START AssignOidcUserRole
client.users.oidc.assign_roles(user_id="custom-user", role_names=["testRole", "viewer"])
# END AssignOidcUserRole
-assert "testRole" in client.users.oidc.get_assigned_roles("custom-user")
-assert "viewer" in client.users.oidc.get_assigned_roles("custom-user")
+assert "testRole" in client.users.oidc.get_assigned_roles(user_id="custom-user")
+assert "viewer" in client.users.oidc.get_assigned_roles(user_id="custom-user")
# START ListOidcUserRoles
-user_roles = client.users.oidc.get_assigned_roles("custom-user")
+user_roles = client.users.oidc.get_assigned_roles(user_id="custom-user")
for role in user_roles:
print(role)
@@ -46,6 +46,6 @@
# START RevokeOidcUserRoles
client.users.oidc.revoke_roles(user_id="custom-user", role_names="testRole")
# END RevokeOidcUserRoles
-assert "testRole" not in client.users.oidc.get_assigned_roles("custom-user")
+assert "testRole" not in client.users.oidc.get_assigned_roles(user_id="custom-user")
client.close()
diff --git a/_includes/code/python/howto.configure.rbac.roles.py b/_includes/code/python/howto.configure.rbac.roles.py
index 9b28ebe8..13c0fa59 100644
--- a/_includes/code/python/howto.configure.rbac.roles.py
+++ b/_includes/code/python/howto.configure.rbac.roles.py
@@ -17,7 +17,7 @@
all_roles = client.roles.list_all()
for role_name, _ in all_roles.items():
- if role_name not in ["viewer", "root", "admin"]:
+ if role_name not in ["viewer", "root", "admin", "read-only"]:
client.roles.delete(role_name=role_name)
# # START CreateRole
@@ -222,8 +222,7 @@
permissions = client.roles.get(role_name="testRole")
assert any(
- permission.alias == "TargetAlias*"
- for permission in permissions.alias_permissions
+ permission.alias == "TargetAlias*" for permission in permissions.alias_permissions
)
client.roles.delete("testRole")
@@ -247,13 +246,34 @@
permissions = client.roles.get(role_name="testRole")
assert any(
- permission.collection == "TargetCollection*" and
- permission.shard == "TargetShard*"
+ permission.collection == "TargetCollection*" and permission.shard == "TargetShard*"
for permission in permissions.replicate_permissions
)
client.roles.delete("testRole")
+# START AddGroupsPermission
+from weaviate.classes.rbac import Permissions
+
+permissions = [
+ Permissions.Groups.oidc(
+ group="TargetGroup*", # Applies to all groups starting with "TargetGroup"
+ read=True, # Allow reading group information
+ assign_and_revoke=True, # Allow assigning and revoking group memberships
+ ),
+]
+
+client.roles.create(role_name="testRole", permissions=permissions)
+# END AddGroupsPermission
+
+permissions = client.roles.get(role_name="testRole")
+assert any(
+ permission.group == "TargetGroup*"
+ for permission in permissions.groups_permissions
+)
+
+client.roles.delete("testRole")
+
permissions = [
Permissions.collections(
collection="TargetCollection*",
diff --git a/docs/weaviate/configuration/rbac/index.mdx b/docs/weaviate/configuration/rbac/index.mdx
index 45dfc78d..2ddbf9d9 100644
--- a/docs/weaviate/configuration/rbac/index.mdx
+++ b/docs/weaviate/configuration/rbac/index.mdx
@@ -400,6 +400,31 @@ Permissions can be defined with the following resources, access levels and optio
+
+
+
+ Groups
+
+
+
+
Read groups
+
Assign and revoke group membership
+
+
+
Group name filter:
+
+
+ string or regex: specifies which groups can be managed
+
+
+
Group type filter:
+
+
+ oidc (only OIDC user groups are supported at the moment)
+
+
+
+
diff --git a/docs/weaviate/configuration/rbac/manage-roles.mdx b/docs/weaviate/configuration/rbac/manage-roles.mdx
index 455d8f9d..3b50c6a6 100644
--- a/docs/weaviate/configuration/rbac/manage-roles.mdx
+++ b/docs/weaviate/configuration/rbac/manage-roles.mdx
@@ -89,6 +89,12 @@ Permissions for these resource types can be assigned to roles:
1. [**Node Data Access**](#nodes-permissions)
+1. [**Collection alias**](#aliases-permissions)
+
+1. [**Replications**](#replications-permissions)
+
+1. [**Groups**](#groups-permissions)
+
#### Create a role with `Role Management` permissions {#role-management-permissions}
This example creates a role called `testRole` with permissions to:
@@ -404,7 +410,7 @@ This example creates a role called `testRole` with permissions to:
-#### Create a role with `Collection Aliases` permissions {#aliases-permissions}
+#### Create a role with `Collection Alias` permissions {#aliases-permissions}
This example creates a role called `testRole` with permissions to:
@@ -480,6 +486,44 @@ This example creates a role called `testRole` with permissions to:
+#### Create a role with `Groups` permissions {#groups-permissions}
+
+This example creates a role called `testRole` with permissions to:
+
+- Read information about and assign/revoke group membership for OIDC groups starting with `TargetGroup`.
+
+
+
+
+
+
+
+```typescript
+// TS/JS support coming soon
+```
+
+
+
+
+```go
+// Go support coming soon
+```
+
+
+
+
+```java
+// Java support coming soon
+```
+
+
+
+
### Grant additional permissions
Additional permissions can be granted to a role at any time. The role must already exist.
diff --git a/tests/docker-compose-rbac.yml b/tests/docker-compose-rbac.yml
index bc029512..acca6207 100644
--- a/tests/docker-compose-rbac.yml
+++ b/tests/docker-compose-rbac.yml
@@ -7,7 +7,7 @@ services:
- '8080'
- --scheme
- http
- image: cr.weaviate.io/semitechnologies/weaviate:1.33.0-dev-4d2ab70.arm64
+ image: cr.weaviate.io/semitechnologies/weaviate:1.33.0-rc.0
ports:
- 8580:8080
- 50551:50051
From e2d146f2664696539d8bcf496584500013bfce08 Mon Sep 17 00:00:00 2001
From: Ivan Despot <66276597+g-despot@users.noreply.github.com>
Date: Thu, 28 Aug 2025 14:59:30 +0200
Subject: [PATCH 13/44] Update docs
---
.../howto/go/docs/manage-data.aliases_test.go | 59 ++-
.../docs/manage-data.collection-aliases.java | 74 ++--
_includes/code/howto/manage-data.aliases.py | 55 ++-
_includes/code/howto/manage-data.aliases.ts | 137 +++---
docs/weaviate/config-refs/collections.mdx | 7 +-
.../manage-collections/collection-aliases.mdx | 9 +-
.../managing-collections/index.mdx | 60 +--
.../_includes/collection_alias_tutorial.png | Bin 0 -> 222210 bytes
docs/weaviate/tutorials/aliases.mdx | 405 ++++++++++++++++++
docs/weaviate/tutorials/index.mdx | 7 +
sidebars.js | 1 +
11 files changed, 615 insertions(+), 199 deletions(-)
create mode 100644 docs/weaviate/tutorials/_includes/collection_alias_tutorial.png
create mode 100644 docs/weaviate/tutorials/aliases.mdx
diff --git a/_includes/code/howto/go/docs/manage-data.aliases_test.go b/_includes/code/howto/go/docs/manage-data.aliases_test.go
index 0d7a9b2c..3ff4ef9b 100644
--- a/_includes/code/howto/go/docs/manage-data.aliases_test.go
+++ b/_includes/code/howto/go/docs/manage-data.aliases_test.go
@@ -19,12 +19,15 @@ func Test_ManageAliases(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
+ // START ConnectToWeaviate
+ // Connect to local Weaviate instance
config := weaviate.Config{
Scheme: "http",
Host: "localhost:8080",
}
client, err := weaviate.NewClient(config)
require.NoError(t, err)
+ // END ConnectToWeaviate
// Check if Weaviate is ready
ready, err := client.Misc().ReadyChecker().Do(ctx)
@@ -40,7 +43,7 @@ func Test_ManageAliases(t *testing.T) {
}
// Clean up collections
- collectionsToDelete := []string{"Articles", "ArticlesV2", "Products_v1", "Products_v2"}
+ collectionsToDelete := []string{"Articles", "ArticlesV2", "Products_v1", "Products_v2", "MyArticles"}
for _, className := range collectionsToDelete {
_ = client.Schema().ClassDeleter().WithClassName(className).Do(ctx)
}
@@ -215,16 +218,6 @@ func Test_ManageAliases(t *testing.T) {
fmt.Printf("Found: %v\n", title)
}
}
-
- // Add a new property using the alias
- property := &models.Property{
- Name: "author",
- DataType: schema.DataTypeText.PropString(),
- }
- err = client.Schema().PropertyCreator().
- WithClassName("MyArticles").
- WithProperty(property).
- Do(ctx)
// UseAlias END
require.NoError(t, err)
@@ -233,8 +226,8 @@ func Test_ManageAliases(t *testing.T) {
})
t.Run("migration example", func(t *testing.T) {
- // MigrationExample START
- // Step 1: Create original collection with data
+ // START Step1CreateOriginal
+ // Create original collection with data
err := client.Schema().ClassCreator().WithClass(&models.Class{
Class: "Products_v1",
Vectorizer: "none",
@@ -265,16 +258,38 @@ func Test_ManageAliases(t *testing.T) {
Do(ctx)
require.NoError(t, err)
+ // END Step1CreateOriginal
- // Step 2: Create alias pointing to current collection
+ // START Step2CreateAlias
+ // Create alias pointing to current collection
err = client.Alias().AliasCreator().WithAlias(&alias.Alias{
Alias: "Products",
Class: "Products_v1",
}).Do(ctx)
require.NoError(t, err)
+ // END Step2CreateAlias
+
+ // START MigrationUseAlias
+ // Your application always uses the alias name "Products"
+ // Insert data through the alias
+ _, err = client.Data().Creator().WithClassName("Products").WithProperties(map[string]interface{}{
+ "name": "Product C",
+ "price": 300,
+ }).Do(ctx)
+ require.NoError(t, err)
+
+ // Query through the alias
+ resp, err := client.Data().ObjectsGetter().WithClassName("Products").WithLimit(5).Do(ctx)
+ require.NoError(t, err)
+ for _, obj := range resp {
+ props := obj.Properties.(map[string]interface{})
+ t.Logf("Product: %v, Price: $%v", props["name"], props["price"])
+ }
+ // END MigrationUseAlias
- // Step 3: Create new collection with updated schema
+ // START Step3NewCollection
+ // Create new collection with updated schema
err = client.Schema().ClassCreator().WithClass(&models.Class{
Class: "Products_v2",
Vectorizer: "none",
@@ -286,8 +301,10 @@ func Test_ManageAliases(t *testing.T) {
}).Do(ctx)
require.NoError(t, err)
+ // END Step3NewCollection
- // Step 4: Migrate data to new collection
+ // START Step4MigrateData
+ // Migrate data to new collection
oldData, err := client.Data().ObjectsGetter().
WithClassName("Products_v1").
Do(ctx)
@@ -306,8 +323,10 @@ func Test_ManageAliases(t *testing.T) {
require.NoError(t, err)
}
+ // END Step4MigrateData
- // Step 5: Switch alias to new collection (instant switch!)
+ // START Step5UpdateAlias
+ // Switch alias to new collection (instant switch!)
err = client.Alias().AliasUpdater().WithAlias(&alias.Alias{
Alias: "Products",
Class: "Products_v2",
@@ -326,10 +345,12 @@ func Test_ManageAliases(t *testing.T) {
if len(result) > 0 {
fmt.Printf("%v\n", result[0].Properties) // Will include the new "category" field
}
+ // END Step5UpdateAlias
- // Step 6: Clean up old collection after verification
+ // START Step6Cleanup
+ // Clean up old collection after verification
err = client.Schema().ClassDeleter().WithClassName("Products_v1").Do(ctx)
- // MigrationExample END
+ // END Step6Cleanup
// Error is expected if collection has data or other dependencies
// In production, you'd want to ensure the collection is empty first
diff --git a/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java b/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java
index 20ebb606..33449886 100644
--- a/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java
+++ b/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java
@@ -30,12 +30,15 @@ class AliasesTest {
@BeforeAll
public static void beforeAll() {
+ // START ConnectToWeaviate
+ // Connect to local Weaviate instance
String scheme = "http";
String host = "localhost";
String port = "8080";
Config config = new Config(scheme, host + ":" + port);
client = new WeaviateClient(config);
+ // END ConnectToWeaviate
}
@BeforeEach
@@ -95,14 +98,10 @@ public void shouldListAllAliases() {
Result> allAliasesResult = client.alias().allGetter().run();
Map allAliases = allAliasesResult.getResult();
- // Filter to show only aliases from this example
for (Map.Entry entry : allAliases.entrySet()) {
Alias aliasInfo = entry.getValue();
- if (aliasInfo.getClassName().equals("Articles") ||
- aliasInfo.getClassName().equals("ArticlesV2")) {
- System.out.println("Alias: " + aliasInfo.getAlias() +
- " -> Collection: " + aliasInfo.getClassName());
- }
+ System.out.println("Alias: " + aliasInfo.getAlias() +
+ " -> Collection: " + aliasInfo.getClassName());
}
// END ListAllAliases
@@ -271,24 +270,12 @@ public void shouldUseAlias() {
System.out.println("Found: " + obj.get("title"));
}
}
-
- // Add a new property using the alias
- Result addPropertyResult = client.schema()
- .propertyCreator()
- .withClassName("MyArticles") // Using alias
- .withProperty(Property.builder()
- .name("author")
- .dataType(Arrays.asList(DataType.TEXT))
- .build())
- .run();
// END UseAlias
assertThat(insertResult).isNotNull()
.returns(false, Result::hasErrors);
assertThat(queryResult).isNotNull()
.returns(false, Result::hasErrors);
- assertThat(addPropertyResult).isNotNull()
- .returns(false, Result::hasErrors);
}
@Test
@@ -312,8 +299,8 @@ public void shouldDeleteAlias() {
@Test
public void shouldPerformMigration() {
- // START MigrationExample
- // Step 1: Create original collection with data
+ // START Step1CreateOriginal
+ // Create original collection with data
WeaviateClass productsV1 = WeaviateClass.builder()
.className("Products_v1")
.build();
@@ -346,14 +333,41 @@ public void shouldPerformMigration() {
client.batch().objectsBatcher()
.withObjects(products.toArray(new WeaviateObject[0]))
.run();
+ // END Step1CreateOriginal
- // Step 2: Create alias pointing to current collection
+ // START Step2CreateAlias
+ // Create alias pointing to current collection
client.alias().creator()
.withClassName("Products_v1")
.withAlias("Products")
.run();
+ // END Step2CreateAlias
+
+ // START MigrationUseAlias
+ // Your application always uses the alias name "Products"
+ // Insert data through the alias
+ Result insertResult = client.data().creator()
+ .withClassName("Products")
+ .withProperties(new HashMap() {{
+ put("name", "Product C");
+ put("price", 300);
+ }})
+ .run();
+
+ // Query through the alias
+ Result> queryResult = client.data().objectsGetter()
+ .withClassName("Products")
+ .withLimit(5)
+ .run();
+ List results = queryResult.getResult();
+ for (WeaviateObject obj : results) {
+ Map props = obj.getProperties();
+ System.out.println("Product: " + props.get("name") + ", Price: $" + props.get("price"));
+ }
+ // END MigrationUseAlias
- // Step 3: Create new collection with updated schema
+ // START Step3NewCollection
+ // Create new collection with updated schema
WeaviateClass productsV2 = WeaviateClass.builder()
.className("Products_v2")
.properties(Arrays.asList(
@@ -375,8 +389,10 @@ public void shouldPerformMigration() {
client.schema().classCreator()
.withClass(productsV2)
.run();
+ // END Step3NewCollection
- // Step 4: Migrate data to new collection
+ // START Step4MigrateData
+ // Migrate data to new collection
Result oldDataResult = client.graphQL()
.get()
.withClassName("Products_v1")
@@ -411,8 +427,10 @@ public void shouldPerformMigration() {
.withObjects(newProducts.toArray(new WeaviateObject[0]))
.run();
}
+ // END Step4MigrateData
- // Step 5: Switch alias to new collection (instant switch!)
+ // START Step5UpdateAlias
+ // Switch alias to new collection (instant switch!)
client.alias().updater()
.withAlias("Products")
.withNewClassName("Products_v2")
@@ -435,12 +453,14 @@ public void shouldPerformMigration() {
List> products_data = (List>) get.get("Products");
System.out.println(products_data.get(0)); // Will include the new "category" field
}
+ // END Step5UpdateAlias
- // Step 6: Clean up old collection after verification
+ // START Step6Cleanup
+ // Clean up old collection after verification
client.schema().classDeleter()
.withClassName("Products_v1")
.run();
- // END MigrationExample
+ // END Step6Cleanup
assertThat(result).isNotNull()
.returns(false, Result::hasErrors);
@@ -464,4 +484,4 @@ private void createArticlesCollection() {
.withClass(articlesClass)
.run();
}
-}
\ No newline at end of file
+}
diff --git a/_includes/code/howto/manage-data.aliases.py b/_includes/code/howto/manage-data.aliases.py
index 9b98e1a7..ee13f735 100644
--- a/_includes/code/howto/manage-data.aliases.py
+++ b/_includes/code/howto/manage-data.aliases.py
@@ -1,8 +1,10 @@
import weaviate
import weaviate.classes as wvc
-# Connect to Weaviate
+# START ConnectToWeaviate
+# Connect to local Weaviate instance
client = weaviate.connect_to_local()
+# END ConnectToWeaviate
# Cleanup
client.alias.delete(alias_name="ArticlesProd")
@@ -32,10 +34,8 @@
# Get all aliases in the instance
all_aliases = client.alias.list_all()
-# Filter to show only aliases from this example
for alias_name, alias_info in all_aliases.items():
- if alias_info.collection in ["Articles", "ArticlesV2"]:
- print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")
+ print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")
# END ListAllAliases
# START ListCollectionAliases
@@ -100,9 +100,6 @@
client.alias.delete(alias_name="ArticlesProd")
# END DeleteAlias
# START UseAlias
-# Create an alias for easier access
-client.alias.create(alias_name="MyArticles", target_collection="Articles")
-
# Use the alias just like a collection name
articles = client.collections.get("MyArticles")
@@ -119,15 +116,10 @@
for obj in results.objects:
print(f"Found: {obj.properties['title']}")
-
-# Add a new property using the alias
-articles.config.add_property(
- wvc.config.Property(name="author", data_type=wvc.config.DataType.TEXT)
-)
# END UseAlias
-# START MigrationExample
-# Step 1: Create original collection with data
+# START Step1CreateOriginal
+# Create original collection with data
client.collections.create(
name="Products_v1", vector_config=wvc.config.Configure.Vectors.self_provided()
)
@@ -136,11 +128,28 @@
products_v1.data.insert_many(
[{"name": "Product A", "price": 100}, {"name": "Product B", "price": 200}]
)
+# END Step1CreateOriginal
-# Step 2: Create alias pointing to current collection
+# START Step2CreateAlias
+# Create alias pointing to current collection
client.alias.create(alias_name="Products", target_collection="Products_v1")
+# END Step2CreateAlias
+
+# START MigrationUseAlias
+# Your application always uses the alias name "Products"
+products = client.collections.use("Products")
+
+# Insert data through the alias
+products.data.insert({"name": "Product C", "price": 300})
+
+# Query through the alias
+results = products.query.fetch_objects(limit=5)
+for obj in results.objects:
+ print(f"Product: {obj.properties['name']}, Price: ${obj.properties['price']}")
+# END MigrationUseAlias
-# Step 3: Create new collection with updated schema
+# START Step3NewCollection
+# Create new collection with updated schema
client.collections.create(
name="Products_v2",
vector_config=wvc.config.Configure.Vectors.self_provided(),
@@ -152,8 +161,10 @@
), # New field
],
)
+# END Step3NewCollection
-# Step 4: Migrate data to new collection
+# START Step4MigrateData
+# Migrate data to new collection
products_v2 = client.collections.get("Products_v2")
old_data = products_v1.query.fetch_objects().objects
@@ -165,18 +176,22 @@
"category": "General", # Default value for new field
}
)
+# END Step4MigrateData
-# Step 5: Switch alias to new collection (instant switch!)
+# START Step5UpdateAlias
+# Switch alias to new collection (instant switch!)
client.alias.update(alias_name="Products", new_target_collection="Products_v2")
# All queries using "Products" alias now use the new collection
products = client.collections.get("Products")
result = products.query.fetch_objects(limit=1)
print(result.objects[0].properties) # Will include the new "category" field
+# END Step5UpdateAlias
-# Step 6: Clean up old collection after verification
+# START Step6Cleanup
+# Clean up old collection after verification
client.collections.delete("Products_v1")
-# END MigrationExample
+# END Step6Cleanup
# Cleanup
diff --git a/_includes/code/howto/manage-data.aliases.ts b/_includes/code/howto/manage-data.aliases.ts
index a5cf8978..e530a619 100644
--- a/_includes/code/howto/manage-data.aliases.ts
+++ b/_includes/code/howto/manage-data.aliases.ts
@@ -1,19 +1,15 @@
-import weaviate, { WeaviateClient} from 'weaviate-client'
+import weaviate, { WeaviateClient } from 'weaviate-client'
const openaiKey = process.env.OPENAI_API_KEY as string
-// Connect to Weaviate
-const client: WeaviateClient = await weaviate.connectToLocal({
- authCredentials: new weaviate.ApiKey('YOUR-WEAVIATE-API-KEY'),
- headers: {
- 'X-OpenAI-Api-Key': openaiKey as string, // Replace with your inference API key
- }
- }
-)
+// START ConnectToWeaviate
+// Connect to local Weaviate instance
+const client: WeaviateClient = await weaviate.connectToLocal()
+// END ConnectToWeaviate
// Cleanup
const aliases = await client.alias.listAll()
-const collections = ["Articles", "ArticlesV2", "ProductsV1", "ProductsV2"]
+const collections = ["Articles", "ArticlesV2", "Products_v1", "Products_v2", "MyArticles"]
if (aliases) {
for (const item of aliases) {
@@ -33,7 +29,7 @@ for (const collection of collections) {
await client.collections.create({
name: "Articles",
vectorizers: weaviate.configure.vectors.selfProvided(),
- properties:[
+ properties: [
{ name: "title", dataType: weaviate.configure.dataType.TEXT },
{ name: "content", dataType: weaviate.configure.dataType.TEXT },
],
@@ -41,8 +37,8 @@ await client.collections.create({
console.log('Created collection "Articles"')
// Create an alias pointing to the collection
-await client.alias.create({
- alias: "ArticlesProd",
+await client.alias.create({
+ alias: "ArticlesProd",
collection: "Articles"
})
@@ -53,9 +49,8 @@ console.log('Created alias "ArticlesProd"')
// Get all aliases in the instance
const allAliases = await client.alias.listAll()
-// Filter to show only aliases from this example
-for (const [aliasName, aliasInfo] of Object.entries(allAliases)) {
- if (["Articles", "ArticlesV2"].includes(aliasInfo.collection)) {
+if (allAliases) {
+ for (const [_, aliasInfo] of Object.entries(allAliases)) {
console.log(`Alias: ${aliasInfo.alias} -> Collection: ${aliasInfo.collection}`);
}
}
@@ -63,10 +58,12 @@ for (const [aliasName, aliasInfo] of Object.entries(allAliases)) {
// START ListCollectionAliases
// Get all aliases pointing to a specific collection
-const collectionAliases = await client.alias.listAll({ collection: "Articles"})
+const collectionAliases = await client.alias.listAll({ collection: "Articles" })
-for (const [aliasName, aliasInfo] of Object.entries(collectionAliases)) {
- console.log(`Alias pointing to Articles: ${aliasInfo.alias}`);
+if (collectionAliases) {
+ for (const [_, aliasInfo] of Object.entries(collectionAliases)) {
+ console.log(`Alias pointing to Articles: ${aliasInfo.alias}`);
+ }
}
// END ListCollectionAliases
@@ -95,7 +92,7 @@ await client.collections.create({
// Update the alias to point to the new collection
await client.alias.update({
- alias: "ArticlesProd",
+ alias: "ArticlesProd",
newTargetCollection: "ArticlesV2"
})
@@ -116,17 +113,16 @@ await client.collections.create({
],
})
// END UseAlias
-// Delete alias if it exists from a previous run
-await client.alias.delete("MyArticles")
// START DeleteAlias
// Delete an alias (the underlying collection remains)
await client.alias.delete("ArticlesProd")
// END DeleteAlias
+
// START UseAlias
// Create an alias for easier access
-await client.alias.create({
- alias: "MyArticles",
+await client.alias.create({
+ alias: "MyArticles",
collection: "Articles"
})
@@ -135,8 +131,8 @@ const articles = client.collections.use("MyArticles")
// Insert data using the alias
await articles.data.insert({
- "title": "Using Aliases in Weaviate",
- "content": "Aliases make collection management easier...",
+ "title": "Using Aliases in Weaviate",
+ "content": "Aliases make collection management easier...",
})
// Query using the alias
@@ -145,36 +141,50 @@ const results = await articles.query.fetchObjects({ limit: 5 })
for (const obj of results.objects) {
console.log(`Found: ${obj.properties['title']}`);
}
-
-// Add a new property using the alias
-await articles.config.addProperty(
- { name: "author", dataType: weaviate.configure.dataType.TEXT }
-)
// END UseAlias
-// START MigrationExample
-// Step 1: Create original collection with data
+// START Step1CreateOriginal
+// Create original collection with data
await client.collections.create({
- name: "ProductsV1",
+ name: "Products_v1",
vectorizers: weaviate.configure.vectors.selfProvided()
})
-const productsV1 = client.collections.use("ProductsV1")
+const products_v1 = client.collections.use("Products_v1")
-await productsV1.data.insertMany([
- {"name": "Product A", "price": 100},
- {"name": "Product B", "price": 200}
+await products_v1.data.insertMany([
+ { "name": "Product A", "price": 100 },
+ { "name": "Product B", "price": 200 }
])
+// END Step1CreateOriginal
-// Step 2: Create alias pointing to current collection
-await client.alias.create({
- alias:"Products",
- collection: "ProductsV1"
+// START Step2CreateAlias
+// Create alias pointing to current collection
+await client.alias.create({
+ alias: "Products",
+ collection: "Products_v1"
})
-// Step 3: Create new collection with updated schema
+// END Step2CreateAlias
+
+// START MigrationUseAlias
+// Your application always uses the alias name "Products"
+const prods = client.collections.use("Products");
+
+// Insert data through the alias
+await prods.data.insert({ name: "Product C", price: 300 });
+
+// Query through the alias
+const res = await prods.query.fetchObjects({ limit: 5 });
+for (const obj of res.objects) {
+ console.log(`Product: ${obj.properties.name}, Price: $${obj.properties.price}`);
+}
+// END MigrationUseAlias
+
+// START Step3NewCollection
+// Create new collection with updated schema
await client.collections.create({
- name: "ProductsV2",
+ name: "Products_v2",
vectorizers: weaviate.configure.vectors.selfProvided(),
properties: [
{ name: "name", dataType: weaviate.configure.dataType.TEXT },
@@ -182,36 +192,39 @@ await client.collections.create({
{ name: "category", dataType: weaviate.configure.dataType.TEXT }, // New field
],
})
+// END Step3NewCollection
-// Step 4: Migrate data to new collection
-const productsV2 = client.collections.use("ProductsV2")
-
-const oldData = (await productsV1.query.fetchObjects()).objects
+// START Step4MigrateData
+// Migrate data to new collection
+const products_v2 = client.collections.use("Products_v2")
+const oldData = (await products_v1.query.fetchObjects()).objects
for (const obj of oldData) {
- productsV2.data.insert({
- "name": obj.properties["name"],
- "price": obj.properties["price"],
- "category": "General", // Default value for new field
+ await products_v2.data.insert({
+ "name": obj.properties["name"],
+ "price": obj.properties["price"],
+ "category": "General", // Default value for new field
})
}
-// Step 5: Switch alias to new collection (instant switch!)
-await client.alias.update({
- alias: "Products",
- newTargetCollection: "ProductsV2"
+// END Step4MigrateData
+
+// START Step5UpdateAlias
+// Switch alias to new collection (instant switch!)
+await client.alias.update({
+ alias: "Products",
+ newTargetCollection: "Products_v2"
})
// All queries using "Products" alias now use the new collection
const products = client.collections.use("Products")
-
const result = await products.query.fetchObjects({ limit: 1 })
-
console.log(result.objects[0].properties) // Will include the new "category" field
+// END Step5UpdateAlias
-// Step 6: Clean up old collection after verification
-await client.collections.delete("ProductsV1")
-// END MigrationExample
-
+// START Step6Cleanup
+// Clean up old collection after verification
+await client.collections.delete("Products_v1")
+// END Step6Cleanup
// Cleanup
const cleanUpAliases = await client.alias.listAll()
diff --git a/docs/weaviate/config-refs/collections.mdx b/docs/weaviate/config-refs/collections.mdx
index e244a269..062debdb 100644
--- a/docs/weaviate/config-refs/collections.mdx
+++ b/docs/weaviate/config-refs/collections.mdx
@@ -880,12 +880,7 @@ For more details, see [Starter Guides: Scaling limits with collections](../start
## Collection aliases
-:::caution Technical preview
-
-Collection aliases were added in **`v1.32`** as a **technical preview**.
-This means that the feature is still under development and may change in future releases, including potential breaking changes.
-**We do not recommend using this feature in production environments at this time.**
-
+:::info Added in `v1.32`
:::
Collection aliases are alternative names for Weaviate collections that allow you to reference a collection by an alternative name.
diff --git a/docs/weaviate/manage-collections/collection-aliases.mdx b/docs/weaviate/manage-collections/collection-aliases.mdx
index 4279dd82..bebd0d95 100644
--- a/docs/weaviate/manage-collections/collection-aliases.mdx
+++ b/docs/weaviate/manage-collections/collection-aliases.mdx
@@ -14,12 +14,7 @@ import TSCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.ts";
import GoCode from "!!raw-loader!/_includes/code/howto/go/docs/manage-data.aliases_test.go";
import JavaCode from "!!raw-loader!/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java";
-:::caution Technical preview
-
-Collection aliases were added in **`v1.32`** as a **technical preview**.
-This means that the feature is still under development and may change in future releases, including potential breaking changes.
-**We do not recommend using this feature in production environments at this time.**
-
+:::info Added in `v1.32`
:::
Collection aliases allow you to create alternative names for your collections. This is useful for changing collection definitions without downtime, A/B testing, or providing more convenient names for collections. An alias acts as a reference to a collection - when you query using an alias name, Weaviate automatically routes the request to the target collection.
@@ -285,7 +280,7 @@ Remove an alias. This only deletes the alias pointer, not the underlying collect
## Using aliases in operations
-Once created, aliases can be used instead of collection names in most operations (except when deleting collections):
+Once created, aliases can be used instead of collection names in all object-related operations, like data import and querying. Aliases cannot be used to update collection definitions or to delete collections.
diff --git a/docs/weaviate/starter-guides/managing-collections/index.mdx b/docs/weaviate/starter-guides/managing-collections/index.mdx
index 51be32a8..72706f2b 100644
--- a/docs/weaviate/starter-guides/managing-collections/index.mdx
+++ b/docs/weaviate/starter-guides/managing-collections/index.mdx
@@ -232,66 +232,10 @@ Sharding settings determine how each collection is sharded and distributed acros
## Collection aliases
-:::caution Technical preview
-
-Collection aliases were added in **`v1.32`** as a **technical preview**.
-This means that the feature is still under development and may change in future releases, including potential breaking changes.
-**We do not recommend using this feature in production environments at this time.**
-
+:::info Added in `v1.32`
:::
-Collection aliases are alternative names (pointers) for Weaviate collections that allow you to reference a collection by multiple names. When you query using an alias, Weaviate automatically routes the request to the target collection. You can set up collection aliases [programmatically through client libraries](../../manage-collections/collection-aliases.mdx) or by using the REST endpoints.
-
-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/manage-data.aliases.py";
-import TSCode from "!!raw-loader!/_includes/code/howto/manage-data.aliases.ts";
-import GoCode from "!!raw-loader!/_includes/code/howto/go/docs/manage-data.aliases_test.go";
-import JavaCode from "!!raw-loader!/_includes/code/howto/java/src/test/java/io/weaviate/docs/manage-data.collection-aliases.java";
-
-### Migration workflow with collection aliases
-
-Collection aliases enable collection migrations with zero downtime. Previously, migrating to a new collection required creating the new collection, pausing your application, updating all collection references in your code, then restarting the application, resulting in service interruption.
-
-Now with aliases, simply create a new collection with your updated collection definition, migrate your data, then instantly [switch the alias](../../manage-collections/collection-aliases.mdx#update-an-alias) to point to the new collection. All your existing queries will continue running uninterrupted. Your application code remains unchanged, as it references the stable alias name rather than the underlying collection.
-
-Here's a complete example showing how to use aliases for a collection migration:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+Collection aliases are alternative names (pointers) for Weaviate collections that allow you to reference a collection by multiple names. When you query using an alias, Weaviate automatically routes the request to the target collection. You can set up collection aliases [programmatically through client libraries](../../manage-collections/collection-aliases.mdx) or by using the REST endpoints.
## Notes
diff --git a/docs/weaviate/tutorials/_includes/collection_alias_tutorial.png b/docs/weaviate/tutorials/_includes/collection_alias_tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..2fd151eee62e57071dbc98cf1ce7fc56296ebd4d
GIT binary patch
literal 222210
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