Merge pull request #1393 from qdrant/doc-strict-mode

[docs] Docs for strict mode
2026-09-28 23:48:31 +02:00 · 2025-01-17 11:50:32 +01:00
parent 56cbe4d42a 3acbe4d841
commit ae53349f83
1 changed files with 344 additions and 1 deletions
@@ -145,6 +145,7 @@ In addition to the required options, you can also specify custom values for the
 * `shard_number` - which defines how many shards the collection should have. See [distributed deployment](/documentation/guides/distributed_deployment/#sharding) section for details.
 * `on_disk_payload` - defines where to store payload data. If `true` - payload will be stored on disk only. Might be useful for limiting the RAM usage in case of large payload.
 * `quantization_config` - see [quantization](/documentation/guides/quantization/#setting-up-quantization-in-qdrant) for details.
+* `strict_mode_config` - see [strict mode](#strict-mode) for details.

 Default parameters for the optional collection parameters are defined in [configuration file](https://github.com/qdrant/qdrant/blob/master/config/config.yaml).

@@ -741,7 +742,7 @@ client, err := qdrant.NewClient(&qdrant.Config{
 })

 client.CreateCollection(context.Background(), &qdrant.CreateCollection{
-	CollectionName: "{collection_namee}",
+	CollectionName: "{collection_name}",
 	SparseVectorsConfig: qdrant.NewSparseVectorsConfig(
 		map[string]*qdrant.SparseVectorParams{
 			"text": {},
@@ -755,6 +756,347 @@ The distance function for sparse vectors is always `Dot` and does not need to be

 However, there are optional parameters to tune the underlying [sparse vector index](/documentation/concepts/indexing/#sparse-vector-index).

+### Strict mode
+
+*Available as of v1.13.0*
+
+Strict mode is a feature to restrict certain type of operations on the collection in order to protect it.
+
+The goal is to prevent inefficient usage patterns that could overload the collections.
+
+This configuration ensures a more predictible and responsive service when you do not have control over the queries that are being executed.
+
+Here is a non exhaustive list of operations that can be restricted using strict mode:
+
+- Preventing querying non indexed payload which can be very slow
+- Maximum number of filtering conditions in a query
+- Maximum batch size when inserting vectors
+- Maximum collection size (in terms of vectors or payload size)
+
+See [schema definitions](https://api.qdrant.tech/api-reference/collections/create-collection#request.body.strict_mode_config) for all the `strict_mode_config` parameters.
+
+Upon crossing a limit, the server will return a client side error with the information about the limit that was crossed.
+
+As part of the config, the `enabled` field act as a toggle to enable or disable the strict mode dynamically.
+
+The `strict_mode_config` can be enabled when [creating](#create-a-collection) a collection, for instance below to active the `unindexed_filtering_retrieve` limit.
+
+```http
+PUT /collections/{collection_name}
+{
+    "strict_mode_config": {
+        "enabled": true,
+        "unindexed_filtering_retrieve": true
+    }
+}
+```
+
+```bash
+curl -X PUT http://localhost:6333/collections/{collection_name} \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "strict_mode_config": {
+        "enabled":" true,
+        "unindexed_filtering_retrieve": true
+    }
+  }'
+```
+
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(url="http://localhost:6333")
+
+client.create_collection(
+    collection_name="{collection_name}",
+    strict_mode_config=models.SparseVectorParams{ enabled=True, unindexed_filtering_retrieve=True },
+)
+```
+
+```typescript
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+const client = new QdrantClient({ host: "localhost", port: 6333 });
+
+client.createCollection("{collection_name}", {
+  strict_mode_config: {
+    enabled: true,
+    unindexed_filtering_retrieve: true,
+  },
+});
+```
+
+```rust
+use qdrant_client::Qdrant;
+use qdrant_client::qdrant::{CreateCollectionBuilder, StrictModeConfigBuilder};
+
+let client = Qdrant::from_url("http://localhost:6334").build()?;
+
+client
+    .create_collection(
+        CreateCollectionBuilder::new("{collection_name}")
+            .strict_config_mode(StrictModeConfigBuilder::default().enabled(true).unindexed_filtering_retrieve(true)),
+    )
+    .await?;
+```
+
+```java
+import io.qdrant.client.QdrantClient;
+import io.qdrant.client.QdrantGrpcClient;
+import io.qdrant.client.grpc.Collections.CreateCollection;
+import io.qdrant.client.grpc.Collections.StrictModeCOnfig;
+
+QdrantClient client =
+    new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());
+
+client
+    .createCollectionAsync(
+        CreateCollection.newBuilder()
+            .setCollectionName("{collection_name}")
+            .setStrictModeConfig(
+                StrictModeConfig.newBuilder().setEnabled(true).setUnindexedFilteringRetrieve(true).build())
+            .build())
+    .get();
+```
+
+```csharp
+using Qdrant.Client;
+using Qdrant.Client.Grpc;
+
+var client = new QdrantClient("localhost", 6334);
+
+await client.CreateCollectionAsync(
+	collectionName: "{collection_name}",
+	strictModeConfig: new StrictModeConfig { enabled = true, unindexed_filtering_retrieve = true }
+);
+```
+
+```go
+import (
+	"context"
+
+	"github.com/qdrant/go-client/qdrant"
+)
+
+client, err := qdrant.NewClient(&qdrant.Config{
+	Host: "localhost",
+	Port: 6334,
+})
+
+client.CreateCollection(context.Background(), &qdrant.CreateCollection{
+	CollectionName: "{collection_name}",
+	StrictModeConfig: &qdrant.StrictModeConfig{
+        Enabled: qdrant.PtrOf(true),
+		IndexingThreshold: qdrant.PtrOf(true),
+	},
+})
+```
+
+Or enable it later on an existing collection through the [collection update](#update-collection-parameters) API:
+
+```http
+PATCH /collections/{collection_name}
+{
+    "strict_mode_config": {
+        "enabled": true,
+        "unindexed_filtering_retrieve": true
+    }
+}
+```
+
+
+```bash
+curl -X PATCH http://localhost:6333/collections/{collection_name} \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "strict_mode_config": {
+        "enabled": true,
+        "unindexed_filtering_retrieve": true
+    }
+  }'
+```
+
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(url="http://localhost:6333")
+
+client.update_collection(
+    collection_name="{collection_name}",
+    strict_mode_config=models.StrictModeConfig(enabled=True, unindexed_filtering_retrieve=True),
+)
+```
+
+```typescript
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+const client = new QdrantClient({ host: "localhost", port: 6333 });
+
+client.updateCollection("{collection_name}", {
+  strict_mode_config: {
+    enabled: true,
+    unindexed_filtering_retrieve: true,
+  },
+});
+```
+
+```rust
+use qdrant_client::qdrant::{StrictModeConfigBuilder, UpdateCollectionBuilder};
+
+client
+    .update_collection(
+        UpdateCollectionBuilder::new("{collection_name}").strict_mode_config(
+            StrictModeConfigBuilder::default().enabled(true).unindexed_filtering_retrieve(true),
+        ),
+    )
+    .await?;
+```
+
+```java
+import io.qdrant.client.grpc.Collections.StrictModeConfigBuilder;
+import io.qdrant.client.grpc.Collections.UpdateCollection;
+
+client.updateCollectionAsync(
+    UpdateCollection.newBuilder()
+        .setCollectionName("{collection_name}")
+        .setStrictModeConfig(
+            StrictModeConfig.newBuilder().setEnabled(true).setUnindexedFilteringRetrieve(true).build())
+        .build());
+```
+
+```csharp
+using Qdrant.Client;
+using Qdrant.Client.Grpc;
+
+var client = new QdrantClient("localhost", 6334);
+
+await client.UpdateCollectionAsync(
+	collectionName: "{collection_name}",
+	strictModeConfig: new StrictModeConfig { Enabled = true, UnindexedFilteringRetrieve = true }
+);
+```
+
+```go
+import (
+	"context"
+
+	"github.com/qdrant/go-client/qdrant"
+)
+
+client, err := qdrant.NewClient(&qdrant.Config{
+	Host: "localhost",
+	Port: 6334,
+})
+
+client.UpdateCollection(context.Background(), &qdrant.UpdateCollection{
+	CollectionName: "{collection_name}",
+	StrictModeConfig: &qdrant.StrictModeConfig{
+        Enabled: qdrant.PtrOf(true),
+		UnindexedFilteringRetrieve: qdrant.PtrOf(true),
+	},
+})
+```
+
+To disable strict mode on an existing collection use:
+
+```http
+PATCH /collections/{collection_name}
+{
+    "strict_mode_config": {
+        "enabled": false
+    }
+}
+```
+
+```bash
+curl -X PATCH http://localhost:6333/collections/{collection_name} \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "strict_mode_config": {
+        "enabled": false,
+    }
+  }'
+```
+
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(url="http://localhost:6333")
+
+client.update_collection(
+    collection_name="{collection_name}",
+    strict_mode_config=models.StrictModeConfig(enabled=False),
+)
+```
+
+```typescript
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+const client = new QdrantClient({ host: "localhost", port: 6333 });
+
+client.updateCollection("{collection_name}", {
+  strict_mode_config: {
+    enabled: false,
+  },
+});
+```
+
+```rust
+use qdrant_client::qdrant::{StrictModeConfigBuilder, UpdateCollectionBuilder};
+
+client
+    .update_collection(
+        UpdateCollectionBuilder::new("{collection_name}").strict_mode_config(
+            StrictModeConfigBuilder::default().enabled(false),
+        ),
+    )
+    .await?;
+```
+
+```java
+import io.qdrant.client.grpc.Collections.StrictModeConfigBuilder;
+import io.qdrant.client.grpc.Collections.UpdateCollection;
+
+client.updateCollectionAsync(
+    UpdateCollection.newBuilder()
+        .setCollectionName("{collection_name}")
+        .setStrictModeConfig(
+            StrictModeConfig.newBuilder().setEnabled(false).build())
+        .build());
+```
+
+```csharp
+using Qdrant.Client;
+using Qdrant.Client.Grpc;
+
+var client = new QdrantClient("localhost", 6334);
+
+await client.UpdateCollectionAsync(
+	collectionName: "{collection_name}",
+	strictModeConfig: new StrictModeConfig { Enabled = false }
+);
+```
+
+```go
+import (
+	"context"
+
+	"github.com/qdrant/go-client/qdrant"
+)
+
+client, err := qdrant.NewClient(&qdrant.Config{
+	Host: "localhost",
+	Port: 6334,
+})
+
+client.UpdateCollection(context.Background(), &qdrant.UpdateCollection{
+	CollectionName: "{collection_name}",
+	StrictModeConfig: &qdrant.StrictModeConfig{
+        Enabled: qdrant.PtrOf(false),
+	},
+})
+```
+
 ### Check collection existence

 *Available as of v1.8.0*
@@ -934,6 +1276,7 @@ The following parameters can be updated:
 * `quantization_config` - see [quantization](/documentation/guides/quantization/#setting-up-quantization-in-qdrant) for details.
 * `vectors_config` - vector-specific configuration, including individual `hnsw_config`, `quantization_config` and `on_disk` settings.
 * `params` - other collection parameters, including `write_consistency_factor` and `on_disk_payload`. 
+* `strict_mode_config` - see [strict mode](#strict-mode) for details.

 Full API specification is available in [schema definitions](https://api.qdrant.tech/api-reference/collections/update-collection).