Skip to main content

Multi-tenancy operations

Multi-tenancy provides data isolation. Each tenant is stored on a separate shard. Data stored in one tenant is not visible to another tenant. If your application serves many different users, multi-tenancy keeps their data private and makes database operations more efficient.

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

Enable multi-tenancy

Multi-tenancy is disabled by default. To enable multi-tenancy, set multiTenancyConfigin the collection definition:

from weaviate.classes.config import Configure

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

Automatically add new tenants

By default, Weaviate returns an error if you try to insert an object into a non-existent tenant. To change this behavior so Weaviate creates a new tenant, set autoTenantCreation to true in the collection definition.

The auto-tenant feature is available from v1.25.0 for batch imports, and from v1.25.2 for single object insertions as well.

Set autoTenantCreation when you create the collection, or reconfigure the collection to update the setting as needed.

Automatic tenant creation is useful when you import a large number of objects. Be cautious if your data is likely to have small inconsistencies or typos. For example, the names TenantOne, tenantOne, and TenntOne will create three different tenants.

Create a collection

from weaviate.classes.config import Configure

multi_collection = client.collections.create(
name="CollectionWithAutoMTEnabled",
# Enable automatic tenant creation
multi_tenancy_config=Configure.multi_tenancy(
enabled=True,
auto_tenant_creation=True
)
)

Update a collection

Use the client to update the auto-tenant creation setting. Auto-tenant is only available for batch inserts.

from weaviate.classes.config import Reconfigure

collection = client.collections.get(collection_name)

collection.config.update(
multi_tenancy_config=Reconfigure.multi_tenancy(auto_tenant_creation=True)
)

Add new tenants manually

To add tenants to a collection, specify the collection and the new tenants. Optionally, specify the tenant activity status as HOT(active, default) or COLD (inactive).

This example adds tenantA to the MultiTenancyCollection collection:

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.

from weaviate.classes.tenants import Tenant

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

List all tenants

List existing tenants in a collection.

This example lists the tenants in the MultiTenancyCollection collection:

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

tenants = multi_collection.tenants.get()

print(tenants)

Get tenants by name

Get tenants from a collection by name. Note that non-existent tenant names are ignored in the response.

This example returns tenantA and tenantB from the MultiTenancyCollection collection:

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

tenant_names = ["tenantA", "tenantB", "nonExistentTenant"] # `nonExistentTenant`` does not exist and will be ignored
tenants_response = multi_collection.tenants.get_by_names(tenant_names)

for k, v in tenants_response.items():
print(k, v)

Get one tenant

Get a particular tenant from a collection.

This example returns a tenant from the MultiTenancyCollection collection:

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

tenant_obj = multi_collection.tenants.get_by_name(tenant_name)

print(tenant_obj.name)

Delete tenants

To delete tenants from a collection, specify the collection and the tenants. The delete operation ignores tenant names if the named tenant is not a part of the collection.

In this example, Weaviate removes tenantB and tenantX from the MultiTenancyCollection collection.

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).

from weaviate.classes.tenants import Tenant

multi_collection = client.collections.get("MultiTenancyCollection")
multi_collection.tenants.update(tenants=[
Tenant(
name="tenantA",
activity_status=weaviate.schema.TenantActivityStatus.COLD
)
])
Additional information
  • This feature was added in v1.21
  • To update the tenant activity status, send a PUT request to the REST API endpoint.

Automatically activate tenants

Added in v1.25.2

Enable this to automatically activate COLD tenants if a read-or-write request comes. This is disabled by default.

from weaviate.classes.config import Configure

multi_collection = client.collections.create(
name="CollectionWithAutoTenantActivation",
multi_tenancy_config=Configure.multi_tenancy(
enabled=True,
auto_tenant_activation=True # Enable automatic tenant activation
)
)

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.

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.

from weaviate.classes.config import ReferenceProperty

multi_collection = client.collections.get("MultiTenancyCollection")
# Add the cross-reference property to the multi-tenancy class
multi_collection.config.add_reference(
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
)

Questions and feedback

If you have any questions or feedback, let us know in the user forum.