From 6e647780abd14c3cbadae8a586413cf21eaf5394 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Wed, 23 Sep 2026 13:22:47 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20named=20vectors=20by=20default=20?= =?UTF-8?q?=E2=80=94=20vector-less=20collections=20and=20the=20auto-schema?= =?UTF-8?q?=20default=20vector?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deploy/migration/index.md | 9 +++++ docs/weaviate/config-refs/collections.mdx | 39 ++++++++++++++++++- .../collection-operations.mdx | 2 + .../manage-collections/vector-config.mdx | 13 ++++++- 4 files changed, 60 insertions(+), 3 deletions(-) diff --git a/docs/deploy/migration/index.md b/docs/deploy/migration/index.md index 13ecc5cc1..8e5d86b06 100644 --- a/docs/deploy/migration/index.md +++ b/docs/deploy/migration/index.md @@ -49,6 +49,15 @@ Between `v1.25` and `v1.27`, there are two minor versions, `v1.26` and `v1.27`. ::: +### Vector configuration defaults (v1.39.1+, v1.40+) {#vector-config-defaults} + +Two defaults for **new** collections changed. Existing collections are untouched, and there is no migration step. + +- From `v1.39.1`, [auto-schema](/weaviate/config-refs/collections.mdx#auto-schema) creates a single named vector called `default` with the vectorizer set to `none`, instead of a [single vector collection](/weaviate/config-refs/collections.mdx#single-vector-collections). [`DEFAULT_VECTORIZER_MODULE`](/deploy/configuration/env-vars/index.md#DEFAULT_VECTORIZER_MODULE) is not applied to it, so supply the vectors yourself for auto-created collections or [add a vector](/weaviate/manage-collections/vector-config.mdx#add-new-named-vectors) after the collection is created. +- From `v1.40`, a collection definition that sets no vector parameters at all creates a [collection without a vector](/weaviate/config-refs/collections.mdx#no-vector). Previously the server defaults filled in the top-level parameters and created a single vector collection. A definition that sets `vectorizer`, `vectorIndexType` or `vectorIndexConfig` is unaffected and still gets the defaults. + +The `v1.40` change is only visible with a client that omits `vectorIndexType` when you do not set one. A client that still sends `vectorIndexType: hnsw` on every collection create keeps getting a single vector collection. The Python client stopped sending it in `v4.21.2`. + ### Raft Migration (v1.25.0+) Weaviate `v1.25.0` introduced Raft [as the consensus algorithm for cluster metadata](/weaviate/concepts/replication-architecture/cluster-architecture#metadata-replication-raft). This requires a one-time migration of the cluster metadata. diff --git a/docs/weaviate/config-refs/collections.mdx b/docs/weaviate/config-refs/collections.mdx index ffcb42120..eee408bdf 100644 --- a/docs/weaviate/config-refs/collections.mdx +++ b/docs/weaviate/config-refs/collections.mdx @@ -573,7 +573,7 @@ Weaviate supports two approaches for vector configuration: - **Single vector collections**: One vector space per object using top-level parameters (`vectorizer`, `vectorIndexType`, `vectorIndexConfig`) - **Multiple named vectors**: Multiple vector spaces per object using the `vectorConfig` parameter (**recommended**) -You cannot combine both approaches in the same collection. +You cannot combine both approaches in the same collection. A definition that uses neither creates a [collection without a vector](#no-vector). :::tip We recommend using `vectorConfig` @@ -598,7 +598,7 @@ Using the `vectorConfig` parameter allows you to start with one vector per colle #### Single vector collections -If you don't explicitly define a [named vector](#named-vectors) in your collection definition, Weaviate automatically creates what's known as a _single vector_ collection. These vectors are stored internally under the named vector `default` (which is a reserved vector name). +A collection that sets any of the top-level `vectorizer`, `vectorIndexType` or `vectorIndexConfig` parameters has one vector space for the whole collection. Weaviate fills in the remaining top-level parameters from the server defaults. To learn which properties of your data are vectorized, refer to the [Configure semantic indexing](./indexing/vector-index.mdx#configure-semantic-indexing) section. @@ -714,6 +714,35 @@ For more code example and configuration guides visit the [How-to: Vectorizer and ::: +#### The `default` vector name {#default-vector-name} + +`default` is a reserved vector name, and it means different things in the two approaches. + +**Single vector collections.** `default` is an alias for the collection's one vector space. Reads and writes that target `default` resolve to it, and a write that sends `vectors: {"default": [...]}` is stored there. The alias is not part of the collection definition, so `GET /v1/schema` returns the top-level parameters and no `vectorConfig` entry. You cannot add a named vector called `default` to such a collection. + +**Collections that use `vectorConfig`.** `default` is an ordinary named vector with no special behavior. It is the name Weaviate gives the vector that [auto-schema](#auto-schema) creates. + +#### Collections without a vector {#no-vector} + +:::info Changed in `v1.40` +::: + +A collection definition that sets none of `vectorizer`, `vectorIndexType`, `vectorIndexConfig` or `vectorConfig` creates a collection with no vector. Before `v1.40`, the server defaults filled in the top-level parameters, so such a definition produced a single vector collection. + +For a collection without a vector: + +- `GET /v1/schema/{collection}` returns none of the vector parameters. +- Objects without vectors are stored as usual. A write that carries a vector is rejected with a `422` error. +- Vector search reports that the collection has no vector index. +- You can [add a named vector](../manage-collections/vector-config.mdx#add-new-named-vectors) later. +- You cannot add the top-level parameters later. An update that sets `vectorizer`, `vectorIndexType` or `vectorIndexConfig` is rejected with a `422` error: + +```text +a class-level vectorizer or vector index cannot be added through an update, add a named vector instead +``` + +Existing collections are unchanged, and a definition that does set the top-level parameters still creates a single vector collection. + --- ### Module configuration @@ -1065,16 +1094,22 @@ After you create a collection, you can [add new properties](../manage-collection ## Auto-schema +:::info Changed in `v1.39.1` +::: + The "Auto-schema" feature generates a collection definition automatically by inferring parameters from data being added. It is enabled by default, and can be disabled (e.g. in `docker-compose.yml`) by setting the environment variable [`AUTOSCHEMA_ENABLED`](/docs/deploy/configuration/env-vars/index.md#AUTOSCHEMA_ENABLED) to `'false'`. It will: - Create a collection if an object is added to a non-existent collection. +- Create a single [named vector](#named-vectors) called `default` for that collection, with the vectorizer set to `none` and the index type taken from [`DEFAULT_VECTOR_INDEX`](/deploy/configuration/env-vars/index.md#DEFAULT_VECTOR_INDEX), or `hnsw` if that variable is unset. Before `v1.39.1`, it created a [single vector collection](#single-vector-collections) instead. - Add any missing property from an object being added. - Infer array data types, such as `int[]`, `text[]`, `number[]`, `boolean[]`, `date[]` and `object[]`. - Infer nested properties for `object` and `object[]` data types. - Throw an error if an object being added contains a property that conflicts with an existing schema type. (e.g. trying to import text into a field that exists in the schema as `int`). +[`DEFAULT_VECTORIZER_MODULE`](/deploy/configuration/env-vars/index.md#DEFAULT_VECTORIZER_MODULE) is not applied to the `default` vector, so auto-schema does not vectorize your data. Supply the vectors yourself, or define the collection before you import. + :::tip Define the collection manually for production use Generally speaking, we recommend that you disable auto-schema for production use. diff --git a/docs/weaviate/manage-collections/collection-operations.mdx b/docs/weaviate/manage-collections/collection-operations.mdx index a53591b3d..50f695bce 100644 --- a/docs/weaviate/manage-collections/collection-operations.mdx +++ b/docs/weaviate/manage-collections/collection-operations.mdx @@ -29,6 +29,8 @@ import VectorConfigSyntax from "/_includes/vector-config-syntax.mdx"; To create a collection, specify at least the collection name. If you don't specify any properties, [`auto-schema`](../config-refs/collections.mdx#auto-schema) creates them. +From `v1.40`, a definition that sets only the name creates a [collection without a vector](../config-refs/collections.mdx#no-vector). + import InitialCaps from "/_includes/schemas/initial-capitalization.md"; diff --git a/docs/weaviate/manage-collections/vector-config.mdx b/docs/weaviate/manage-collections/vector-config.mdx index b27bf712b..f640be761 100644 --- a/docs/weaviate/manage-collections/vector-config.mdx +++ b/docs/weaviate/manage-collections/vector-config.mdx @@ -129,6 +129,17 @@ To configure how a vectorizer works (i.e. what model to use) with a specific col +## Create a collection without a vector + +:::info Changed in `v1.40` +::: + +To create a collection without a vector, set no vector parameters at all — no `vectorizer`, `vectorIndexType` or `vectorIndexConfig`, and no named vectors. From `v1.40`, Weaviate no longer fills these in from the server defaults, so vector search is not available on the collection. For the rest of the behavior, see [Collections without a vector](/weaviate/config-refs/collections.mdx#no-vector). + +You can [add a named vector](#add-new-named-vectors) to it later. The top-level `vectorizer`, `vectorIndexType` and `vectorIndexConfig` parameters cannot be added after creation. + +The change is only visible with a client that omits `vectorIndexType` when you do not set one; the Python client does so from `v4.21.2`. See [Vector configuration defaults](/deploy/migration/index.md#vector-config-defaults). + ## Define named vectors You can define multiple [named vectors](../concepts/data.md#multiple-vector-embeddings-named-vectors) per collection. This allows each object to be represented by multiple vector embeddings, each with its own vector index. @@ -182,7 +193,7 @@ As such, each named vector configuration can include its own vectorizer and vect -Named vectors can be added to existing collection definitions with named vectors. (This is not possible for collections without named vectors.) +Named vectors can be added to a collection that already has named vectors, and to a [collection created without a vector](#create-a-collection-without-a-vector). You cannot add one to a [single vector collection](/weaviate/config-refs/collections.mdx#single-vector-collections).