Skip to main content

Multi-tenancy operations

Multi-tenancy isolates data between tenants (typically end users) in a Weaviate instance, for example in a SaaS application. Each tenant is a separate shard in Weaviate.

Multi-tenancy availability
  • Multi-tenancy added in v1.20
  • (Experimental) Tenant activity status setting added in v1.21

Enable multi-tenancy

Multi-tenancy is disabled by default. To enable it, set the multiTenancyConfig variable in the collection definition as shown below:

    import weaviate.classes as wvc

multi_collection = client.collections.create(
name="MultiTenancyCollection",
# Enable multi-tenancy on the new collection
multi_tenancy_config=wvc.config.Configure.multi_tenancy(True)
)

Add tenant(s)

Add tenants to a collection (MultiTenancyCollection) with a name (e.g. tenantA) and an optional tenant activity status as HOT(active, default) or COLD (inactive).

Additional information

Tenant status is available from Weaviate 1.21 onwards.


Allowable tenant names

A tenant name can only contain alphanumeric characters (a-z, A-Z, 0-9), underscore (_), and hyphen (-), with a length of 4 to 64 characters.

    import weaviate.classes as wvc

# Add two tenants to the collection
multi_collection.tenants.create(
tenants=[
wvc.tenants.Tenant(name="tenantA"),
wvc.tenants.Tenant(name="tenantB"),
]
)

List tenant(s)

List existing tenants in a collection (e.g.MultiTenancyCollection):

    multi_collection = client.collections.get("MultiTenancyCollection")
tenants = multi_collection.tenants.get()

print(tenants)

Delete tenant(s)

Delete one or more existing tenants in a collection (e.g. MultiTenancyCollection) and tenant names (e.g. ["tenantB", "tenantX"]).

Non-existing tenants are ignored.

    multi_collection = client.collections.get("MultiTenancyCollection")

# Remove a list of tenants - tenantX will be ignored.
multi_collection.tenants.remove(["tenantB", "tenantX"])

Update tenant activity status

Update existing tenants' activity status to active (HOT) or inactive (COLD).

    multi_collection = client.collections.get("MultiTenancyCollection")
multi_collection.tenants.update(tenants=[
wvc.tenants.Tenant(
name="tenantA",
activity_status=weaviate.schema.TenantActivityStatus.COLD
)
])
Additional information

CRUD operations

Multi-tenancy collections require tenant name (e.g. tenantA) with each CRUD operation, as shown in the object creation example below.

    multi_collection = client.collections.get("MultiTenancyCollection")

# Get collection specific to the required tenant
multi_tenantA = multi_collection.with_tenant("tenantA")

# Insert an object to tenantA
object_id = multi_tenantA.data.insert(
properties={
"question": "This vector DB is OSS & supports automatic property type inference on import"
}
)

Search queries

Multi-tenancy collections require the tenant name (e.g. tenantA) with each Get and Aggregate query operation.

    import weaviate.classes as wvc

multi_collection = client.collections.get("MultiTenancyCollection")

# Get collection specific to the required tenant
multi_tenantA = multi_collection.with_tenant("tenantA")

# Query tenantA
result = multi_tenantA.query.fetch_objects(
limit=2,
)

print(result.objects[0].properties)

Cross-references

A cross-reference can be added from a multi-tenancy collection object to:

  • A non-multi-tenancy collection object, or
  • An object belonging to the same tenant.

Multi-tenancy collections require the tenant name (e.g. tenantA) when creating, updating or deleting cross-references.

    import weaviate.classes as wvc

multi_collection = client.collections.get("MultiTenancyCollection")
# Add the cross-reference property to the multi-tenancy class
multi_collection.config.add_reference(
wvc.config.ReferenceProperty(
name="hasCategory",
target_collection="JeopardyCategory"
)
)

# Get collection specific to the required tenant
multi_tenantA = multi_collection.with_tenant(tenant="tenantA")

# Add reference from MultiTenancyCollection object to a JeopardyCategory object
multi_tenantA.data.reference_add(
from_uuid=object_id, # MultiTenancyCollection object id (a Jeopardy question)
from_property="hasCategory",
to=category_id # JeopardyCategory id
)