Your First Weaviate Collection

In Weaviate, a collection is the top-level container for a type of object. For a WooCommerce agency, a collection might represent products, product documentation, orders, support articles, or store policies. It defines the properties stored on each object and the vector configuration used for semantic search.

Choose a collection boundary

Start with one business concept rather than creating a single collection for every record in a store. A Product collection is a sensible first example because product data commonly supports search, recommendations, merchandising, and support workflows.

A useful product record might include:

sku for the WooCommerce product identifier
name for the product title
description for searchable product content
categories for taxonomy values
price for filtering or display metadata
permalink for linking search results back to the store

Do not automatically copy every WooCommerce field into the vector database. Keep operational data such as stock quantity, tax configuration, and order relationships in WooCommerce or the system of record unless the application specifically needs them in Weaviate.

Connect to a local instance

The following example assumes a local Weaviate instance is running and that the Python client is installed:

pip install -U weaviate-client

For a local Docker deployment, the v4 Python client can connect with connect_to_local():

import weaviate

client = weaviate.connect_to_local()

If your deployment uses a hosted vectorizer such as OpenAI, configure the required API key before creating the collection. The vectorizer configuration determines how Weaviate converts selected text properties into vectors.

Create the Product collection

This example uses the v4 Python client and an OpenAI text vectorizer. The exact vectorizer must match the modules enabled by your Weaviate deployment.

import weaviate
from weaviate.classes.config import Configure, DataType, Property

client = weaviate.connect_to_local()

try:
    products = client.collections.create(
        name="Product",
        properties=[
            Property(name="sku", data_type=DataType.TEXT),
            Property(name="name", data_type=DataType.TEXT),
            Property(name="description", data_type=DataType.TEXT),
            Property(name="categories", data_type=DataType.TEXT_ARRAY),
            Property(name="price", data_type=DataType.NUMBER),
            Property(name="permalink", data_type=DataType.TEXT),
        ],
        vector_config=Configure.Vectors.text2vec_openai(
            source_properties=["name", "description", "categories"]
        ),
    )
finally:
    client.close()

The collection name is Product. Property names are explicit, which makes the schema easier to inspect and keeps the indexed text focused on the fields that influence semantic matching.

Use an existing collection

Collection creation is normally a deployment or migration task. Application code that runs during a search request should retrieve an existing collection instead of attempting to create it on every request.

import weaviate

client = weaviate.connect_to_local()

try:
    products = client.collections.get("Product")
    print(products)
finally:
    client.close()

In a production integration, run schema creation separately during provisioning. This avoids race conditions when multiple PHP workers, queue workers, or deployment processes start at the same time.

Insert a WooCommerce product

Once the collection exists, insert properties using a normalized payload from the WooCommerce REST API, a webhook handler, or a synchronization job.

import weaviate

client = weaviate.connect_to_local()

try:
    products = client.collections.get("Product")

    product_id = products.data.insert(
        properties={
            "sku": "WOO-HOODIE-001",
            "name": "Classic Cotton Hoodie",
            "description": "A midweight cotton hoodie with a brushed interior and relaxed fit.",
            "categories": ["Clothing", "Hoodies"],
            "price": 59.00,
            "permalink": "https://store.example.com/product/classic-cotton-hoodie/",
        }
    )

    print(product_id)
finally:
    client.close()

Keep a stable identifier from WooCommerce available in the object. You can use the SKU as a property, or supply a deterministic UUID when your synchronization process needs repeatable upserts. A stable identifier helps prevent duplicate objects when the same product is processed by both a webhook and a scheduled import.

Run a first semantic query

After the product has been vectorized, query the collection with language rather than an exact product title:

import weaviate

client = weaviate.connect_to_local()

try:
    products = client.collections.get("Product")
    response = products.query.near_text(
        query="warm casual clothing for cool weather",
        limit=3,
    )

    for item in response.objects:
        print(item.properties["name"])
        print(item.properties["permalink"])
finally:
    client.close()

The query compares the input text with vectors generated from the configured source properties. It is not a replacement for exact filters. For example, use a semantic query to find relevant products, then apply business rules such as catalog visibility, price range, stock status, or customer eligibility in the appropriate query layer.

Plan the collection for synchronization

A WooCommerce integration should define how creates, updates, and deletes are reflected in Weaviate:

Insert a new object when a product becomes searchable.
Update properties when the title, description, categories, price, or permalink changes.
Remove or mark the object unavailable when the product is deleted, hidden, or no longer part of the searchable catalog.
Run a reconciliation job to detect missed webhooks and stale objects.

Prices and stock are especially time-sensitive. If search results display current commercial data, either synchronize those fields promptly or retrieve the authoritative values from WooCommerce before rendering the result.

Inspect and evolve the schema

Before adding a property, decide whether it is descriptive text, structured metadata, or an identifier. Descriptive fields may contribute to embeddings; structured fields are usually better suited to filtering and sorting. If the initial design is wrong, create a migration plan rather than changing production data casually.

For an agency project, store the collection definition in version-controlled provisioning code and document the Weaviate server version, client version, vectorizer, source properties, and synchronization rules. That turns the collection from an ad hoc experiment into a reproducible part of the store architecture.

Table of contents :