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
• Auto-tenant creation for batch imports added in v1.25.0
• Auto-tenant creation for single object insertions added in v1.25.2
• Auto-tenant activation added in v1.25.2

Tenant status renamed in v1.26

In v1.26, the HOT status was renamed to ACTIVE and the COLD status was renamed to INACTIVE.

Enable multi-tenancy

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

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

const result = await client.collections.create({
  name: collectionName,
  multiTenancy: weaviate.configure.multiTenancy({ enabled: true })
})

client.Schema().ClassCreator().
  WithClass(&models.Class{
  	Class: "MultiTenancyCollection",
  	MultiTenancyConfig: &models.MultiTenancyConfig{
  		Enabled: true,
  	},
  }).
  Do(ctx)

client.collections.create("MultiTenancyCollection",
    col -> col.multiTenancy(mt -> mt.enabled(true)));

WeaviateClass multiTenancyCollection = WeaviateClass.builder()
  .className("MultiTenancyCollection")
  .multiTenancyConfig(MultiTenancyConfig.builder().enabled(true).build())
  .build();

client.schema().classCreator()
  .withClass(multiTenancyCollection)
  .run();

await client.Collections.Create(new CollectionConfig
{
    Name = "MultiTenancyCollection",
    MultiTenancyConfig = new MultiTenancyConfig { 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

PythonJavaScript/TypeScriptGoJava v6 (Beta)C# (Beta)Curl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

const result = await client.collections.create({
  name: collectionName,
  multiTenancy: weaviate.configure.multiTenancy({
    enabled: true,
    autoTenantCreation: true
  })
})

func createClassWithAutoTenantEnabled(ctx context.Context, client *weaviate.Client) {
	class := &models.Class{
		Class: "AutoTenantEnabledOnCreate",
		Properties: []*models.Property{
			{Name: "textProp", DataType: []string{"text"}},
		},
		MultiTenancyConfig: &models.MultiTenancyConfig{
			Enabled:            true,
			AutoTenantCreation: true,
		},
	}
	err := client.Schema().ClassCreator().WithClass(class).Do(ctx)
	if err != nil {
		log.Fatalf("create class: %v", err)
	}
}

client.collections.create("CollectionWithAutoMTEnabled",
    col -> col.multiTenancy(mt -> mt.autoTenantCreation(true)));

await client.Collections.Create(new CollectionConfig
{
    Name = "CollectionWithAutoMTEnabled",
    MultiTenancyConfig = new MultiTenancyConfig { Enabled = true, AutoTenantCreation = true }
});

curl localhost:8080/v1/schema -H 'content-type:application/json' -d \
'{
  "class": "Customer",
  "properties": [
    {
      "name": "customer_name",
      "dataType": ["text"]
    },
    {
      "name": "customer_category",
      "dataType": ["text"]
    }
  ],
  "multiTenancyConfig": {
    "enabled": true,
    "autoTenantCreation": true
  }
}'

Update a collection

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

PythonJavaScript/TypeScriptGoJava v6 (Beta)C# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import Reconfigure

collection = client.collections.use(collection_name)

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

import { reconfigure } from 'weaviate-client';

const multiCollection = client.collections.use(collectionName);

await multiCollection.config.update({
  multiTenancy: weaviate.reconfigure.multiTenancy({
    autoTenantActivation: true,
    autoTenantCreation: true,
  }),
});

	existing, err := client.Schema().ClassGetter().
		WithClassName(class.Class).Do(ctx)
	if err != nil {
		log.Fatalf("get existing class %q: %v", class.Class, err)
	}

	existing.MultiTenancyConfig.AutoTenantCreation = true

	err = client.Schema().ClassUpdater().WithClass(existing).Do(ctx)
	if err != nil {
		log.Fatalf("enable autotenant: %v", err)
	}

CollectionHandle<Map<String, Object>> collection =
    client.collections.use(collectionName);
collection.config
    .update(col -> col.multiTenancy(mt -> mt.autoTenantCreation(true)));

var collection = client.Collections.Use(collectionName);
await collection.Config.Update(c =>
{
    c.MultiTenancyConfig.AutoTenantCreation = 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 ACTIVE(available, default), INACTIVE (not available, on disk), or OFFLOADED (not available, offloaded to cloud).

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.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.tenants import Tenant

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

const multiCollection = client.collections.use(collectionName);

await multiCollection.tenants.create([
  { name: 'tenantA' },
  { name: 'tenantB' }
])

client.Schema().TenantsCreator().
  WithClassName("MultiTenancyCollection").
  WithTenants(models.Tenant{Name: "tenantA"}, models.Tenant{Name: "tenantB"}).
  Do(ctx)

collection.tenants.create(Tenant.active("tenantA"),
    Tenant.active("tenantB"));

client.schema().tenantsCreator()
  .withClassName("MultiTenancyCollection")
  .withTenants(
    Tenant.builder().name("tenantA").build(),
    Tenant.builder().name("tenantB").build()
  )
  .run();

await collection.Tenants.Add(
    new Tenant { Name = "tenantA" },
    new Tenant { Name = "tenantB" }
);

List all tenants

List existing tenants in a collection.

This example lists the tenants in the MultiTenancyCollection collection:

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

tenants = multi_collection.tenants.get()

print(tenants)

const multiCollection = client.collections.use(collectionName);

let tenants = await multiCollection.tenants.get()

console.log(tenants)

tenants, err := client.Schema().TenantsGetter().
  WithClassName("MultiTenancyCollection").
  Do(ctx)

List<Tenant> tenants = collection.tenants.get();
System.out.println(tenants);

client.schema().tenantsGetter()
  .withClassName("MultiTenancyCollection")
  .run();

var tenants = await collection.Tenants.List();
foreach (var t in tenants) Console.WriteLine(t.Name);

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:

PythonJavaScript/TypeScriptJava v6 (Beta)C# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

multi_collection = client.collections.use("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)

const multiCollection = client.collections.use(collectionName);

const tenants = await multiCollection.tenants.getByNames(['tenantA', 'tenantB'])
console.log(tenants)

List<String> tenantNames =
    Arrays.asList("tenantA", "tenantB", "nonExistentTenant");
List<Tenant> tenants = collection.tenants.get(tenantNames);
System.out.println(tenants);

var tenantNames = new[] { "tenantA", "tenantB", "nonExistentTenant" };
var tenants = await collection.Tenants.List(tenantNames);
foreach (var t in tenants) Console.WriteLine(t.Name);

Get one tenant

Get a particular tenant from a collection.

This example returns a tenant from the MultiTenancyCollection collection:

PythonJavaScript/TypeScriptJava v6 (Beta)C# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

tenant_obj = multi_collection.tenants.get_by_name(tenant_name)

print(tenant_obj.name)

const multiCollection = client.collections.use(collectionName);

const tenant = await multiCollection.tenants.getByName('tenantA')
console.log(tenant)

String tenantName = "tenantA";
Optional<Tenant> tenant = collection.tenants.get(tenantName);
System.out.println(tenant);

string tenantName = "tenantA";
var tenant = await collection.Tenants.Get(tenantName);
Console.WriteLine(tenant?.Name);

Delete tenants

To delete tenants from a collection, specify the collection (e.g. MultiTenancyCollection) and the tenants (tenantB and tenantX). The delete operation ignores tenant names if a named tenant is not a part of the collection.

Tenant deletion == Tenant data deletion

Deleting a tenant deletes all associated objects.

PythonJavaScript/TypeScriptGoJava v6 (Beta)JavaC# (Beta)

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

const multiCollection = client.collections.use(collectionName);

await multiCollection.tenants.remove([
  { name: 'tenantB' },
  { name: 'tenantX' }  // tenantX will be ignored
])

client.Schema().TenantsDeleter().
  WithClassName("MultiTenancyCollection").
  WithTenants("tenantB", "tenantX"). // tenantX will be ignored
  Do(ctx)

collection.tenants.delete(Arrays.asList("tenantB", "tenantX"));

client.schema().tenantsDeleter()
  .withClassName("MultiTenancyCollection")
  .withTenants("tenantB", "tenantX") // tenantX will be ignored
  .run();

await collection.Tenants.Delete(new[] { "tenantB", "tenantX" });

Manage tenant states

Change a tenant state between ACTIVE, INACTIVE, and OFFLOADED.

PythonJavaScript/TypeScript

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.tenants import Tenant, TenantActivityStatus

multi_collection = client.collections.use("MultiTenancyCollection")
multi_collection.tenants.update(tenants=[
    Tenant(
        name="tenantA",
        activity_status=TenantActivityStatus.ACTIVE # INACTIVE, OFFLOADED
    )
])

const multiCollection = client.collections.use(collectionName)

await multiCollection.tenants.update({
  name: 'tenantA',
  activityStatus: 'ACTIVE' // 'INACTIVE', 'OFFLOADED'
})

Learn more

See How-to: Manage tenant states for more hands-on examples, and the Guide: Manage resources for more information and strategies to manage hot, warm and cold storage tiers.

CRUD operations

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

PythonJavaScript/TypeScriptGoJava

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

multi_collection = client.collections.use("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"
    }
)

const multiCollection = client.collections.use(collectionName);

const multiTenantA = multiCollection.withTenant('tenantA')

await multiTenantA.data.insert({
  question: 'This vector DB is OSS & supports automatic property type inference on import'
})

object, err := client.Data().Creator().
  WithClassName("MultiTenancyCollection"). // The class to which the object will be added
  WithProperties(map[string]interface{}{
  	"question": "This vector DB is OSS & supports automatic property type inference on import",
  }).
  WithTenant("tenantA"). // The tenant to which the object will be added
  Do(ctx)

Result<WeaviateObject> result = client.data().creator()
  .withClassName("MultiTenancyCollection") // The class to which the object will be added
  .withProperties(new HashMap<String, Object>() {{
    put("question", "This vector DB is OSS & supports automatic property type inference on import");
  }})
  .withTenant("tenantA") // The tenant to which the object will be added
  .run();

Search queries

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

PythonJavaScript/TypeScriptGoJava

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

multi_collection = client.collections.use("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)

const multiCollection = client.collections.use(collectionName);

const multiTenantA = multiCollection.withTenant('tenantA')

const objectA = await multiTenantA.query.fetchObjects({
  limit: 2
})

console.log(objectA.objects)

result, err := client.GraphQL().Get().
  WithClassName("MultiTenancyCollection").
  WithFields(graphql.Field{Name: "question"}).
  WithTenant("tenantA").
  Do(ctx)

Result<GraphQLResponse> result = client.graphQL().get()
  .withClassName("MultiTenancyCollection")
  .withFields(Field.builder().name("question").build())
  .withTenant("tenantA")
  .run();

Cross-references

Cross-references and query performance

Queries involving cross-references can be slower than queries that do not involve cross-references, especially at scale such as for multiple objects or complex queries.

At the first instance, we strongly encourage you to consider whether you can avoid using cross-references in your data schema. As a scalable AI database, Weaviate is well-placed to perform complex queries with vector, keyword and hybrid searches involving filters. You may benefit from rethinking your data schema to avoid cross-references where possible.

For example, instead of creating separate "Author" and "Book" collections with cross-references, consider embedding author information directly in Book objects and using searches and filters to find books by author characteristics.

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.

PythonJavaScript/TypeScriptGoJava

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

from weaviate.classes.config import ReferenceProperty

multi_collection = client.collections.use("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
)

const multiCollection = client.collections.use(collectionName);
// Add the cross-reference property to the multi-tenancy class

await multiCollection.config.addReference({
  name: 'hasCategory',
  targetCollection: 'JeopardyCategory'
})

const multiTenantA = multiCollection.withTenant('tenantA')

await multiTenantA.data.referenceAdd({
  fromUuid: objectId,
  fromProperty: 'hasCategory',
  to: categoryId
})

// Add the cross-reference property to the multi-tenancy class
client.Schema().PropertyCreator().
  WithClassName("MultiTenancyCollection").
  WithProperty(&models.Property{
  	Name:     "hasCategory",
  	DataType: []string{"JeopardyCategory"},
  }).
  Do(ctx)

// Create the cross-reference from MultiTenancyCollection object to the JeopardyCategory object
client.Data().ReferenceCreator().
  WithClassName("MultiTenancyCollection").
  WithTenant("tenantA").
  WithID(object.ID.String()). // MultiTenancyCollection object id (a Jeopardy question)
  WithReferenceProperty("hasCategory").
  WithReference(client.Data().ReferencePayloadBuilder().
  	WithClassName("JeopardyCategory").
  	WithID(category.ID.String()).
  	Payload()).
  Do(ctx)

// Add the cross-reference property to the multi-tenancy class
client.schema().propertyCreator()
  .withClassName("MultiTenancyCollection")
  .withProperty(Property.builder()
    .name("hasCategory")
    .dataType(Collections.singletonList("JeopardyCategory")).build()
  )
  .run();

// Create the cross-reference from MultiTenancyCollection object to the JeopardyCategory object
client.data().referenceCreator()
  .withClassName("MultiTenancyCollection")
  .withTenant("tenantA")
  .withID(object.getId()) // MultiTenancyCollection object id (a Jeopardy question)
  .withReferenceProperty("hasCategory")
  .withReference(
    client.data()
      .referencePayloadBuilder()
      .withClassName("JeopardyCategory")
      .withID(category.getId())
      .payload()
  )
  .run();

Backups

Backups do not include inactive or offloaded tenants

Backups of multi-tenant collections will only include active tenants, and not inactive or offloaded tenants. Activate tenants before creating a backup to ensure all data is included.

Related pages

• Connect to Weaviate
• How to: Manage collections

• References: REST API: Schema

• Concepts: Data Structure: Multi-tenancy

Questions and feedback

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

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.