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

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:

Python Client v4

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

  API docs

Python Client v3

client.schema.create_class({
    "class": "MultiTenancyCollection",
    "multiTenancyConfig": {"enabled": True}
})

  API docs  Deprecated (v3)

JS/TS Client v3

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

  API docs

JS/TS Client v2

await client.schema
  .classCreator().withClass({
    class: 'MultiTenancyCollection',
    multiTenancyConfig: { enabled: true },
  })
  .do();

Java

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

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

  API docs

Go

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

  API docs

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

Python Client v4

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

  API docs

JS/TS Client v3

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

  API docs

Go

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

cURL

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
  }
}'

  API docs

Update a collection

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

Python Client v4

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

  API docs

JS/TS Client v3

import { reconfigure } from 'weaviate-client';

const multiCollection = client.collections.get('MultiTenancyCollection');

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

  API docs

Go

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

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.

Python Client v4

from weaviate.classes.tenants import Tenant

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

  API docs

Python Client v3

from weaviate import Tenant

client.schema.add_class_tenants(
  class_name="MultiTenancyCollection",  # The class to which the tenants will be added
  tenants=[Tenant(name="tenantA"), Tenant(name="tenantB")]
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection =  client.collections.get('MultiTenancyCollection');

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

  API docs

JS/TS Client v2

let tenants = await client.schema
  .tenantsCreator(
    'MultiTenancyCollection',
    [{ name: 'tenantA' }, { name: 'tenantB' }]
  )
  .do();

Java

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

  API docs

Go

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

  API docs

List all tenants

List existing tenants in a collection.

This example lists the tenants in the MultiTenancyCollection collection:

Python Client v4

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

tenants = multi_collection.tenants.get()

print(tenants)

  API docs

Python Client v3

tenants = client.schema.get_class_tenants(
    class_name="MultiTenancyCollection"  # The class from which the tenants will be retrieved
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection =  client.collections.get('MultiTenancyCollection');

let tenants = await multiCollection.tenants.get()

console.log(tenants)

  API docs

JS/TS Client v2

tenants = await client.schema
  .tenantsGetter('MultiTenancyCollection')
  .do();

Java

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

  API docs

Go

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

  API docs

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:

Python Client v4

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)

  API docs

JS/TS Client v3

const multiCollection = client.collections.get('MultiTenancyCollection');

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

  API docs

Get one tenant

Get a particular tenant from a collection.

This example returns a tenant from the MultiTenancyCollection collection:

Python Client v4

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

tenant_obj = multi_collection.tenants.get_by_name(tenant_name)

print(tenant_obj.name)

  API docs

JS/TS Client v3

const multiCollection = client.collections.get('MultiTenancyCollection');

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

  API docs

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.

Python Client v4

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

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

  API docs

Python Client v3

client.schema.remove_class_tenants(
    class_name="MultiTenancyCollection",  # The class from which the tenants will be removed
    tenants=["tenantB", "tenantX"]  # The tenants to be removed. tenantX will be ignored.
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection = client.collections.get('MultiTenancyCollection');

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

  API docs

JS/TS Client v2

await client.schema
  .tenantsDeleter('MultiTenancyCollection', ['tenantB', 'tenantX'])  // tenantX will be ignored
  .do();

Java

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

  API docs

Go

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

  API docs

Manage tenant states

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

Python Client v4

from weaviate.classes.tenants import Tenant, TenantActivityStatus

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

  API docs

JS/TS Client v3

const multiCollection = client.collections.get('MultiTenancyCollection')

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

  API docs

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.

Python Client v4

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

  API docs

Python Client v3

object_id = client.data_object.create(
      class_name="MultiTenancyCollection",  # The class to which the object will be added
      data_object={
          "question": "This vector DB is OSS & supports automatic property type inference on import"
      },
      tenant="tenantA"  # The tenant to which the object will be added
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection =  client.collections.get('MultiTenancyCollection');

const multiTenantA = multiCollection.withTenant('tenantA')

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

  API docs

JS/TS Client v2

let object = await client.data.creator()
  .withClassName('MultiTenancyCollection')  // The class to which the object will be added
  .withProperties({
    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();

Java

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

  API docs

Go

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)

  API docs

Search queries

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

Python Client v4

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)

  API docs

Python Client v3

result = (
    client.query.get("MultiTenancyCollection", ["question"])
    .with_tenant("tenantA")
    .do()
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection = client.collections.get('MultiTenancyCollection');

const multiTenantA = multiCollection.withTenant('tenantA')

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

console.log(objectA.objects)

  API docs

JS/TS Client v2

const result = await client.graphql
  .get()
  .withClassName('MultiTenancyCollection')
  .withFields('question')
  .withTenant('tenantA')
  .do();

Java

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

  API docs

Go

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

  API docs

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.

Python Client v4

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
)

  API docs

Python Client v3

# Add the cross-reference property to the multi-tenancy class
client.schema.property.create("MultiTenancyCollection", {
    "name": "hasCategory",
    "dataType": ["JeopardyCategory"],
})

client.data_object.reference.add(
    from_uuid=object_id,  # MultiTenancyCollection object id (a Jeopardy question)
    from_class_name="MultiTenancyCollection",
    from_property_name="hasCategory",
    tenant="tenantA",
    to_class_name="JeopardyCategory",
    to_uuid=category_id
)

  API docs  Deprecated (v3)

JS/TS Client v3

const multiCollection =  client.collections.get('MultiTenancyCollection');
// 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
})

  API docs

JS/TS Client v2

// Add the cross-reference property to the multi-tenancy class
await client.schema.propertyCreator()
  .withClassName('MultiTenancyCollection')
  .withProperty({
    'name': 'hasCategory',
    'dataType': ['JeopardyCategory'],
  })
  .do();

// Create the cross-reference from MultiTenancyCollection object to the JeopardyCategory object
await client.data
  .referenceCreator()
  .withClassName('MultiTenancyCollection')
  .withTenant('tenantA')
  .withId(object.id)  // MultiTenancyCollection object id (a Jeopardy question)
  .withReferenceProperty('hasCategory')
  .withReference(
    client.data
      .referencePayloadBuilder()
      .withClassName('JeopardyCategory')
      .withId(category.id)
      .payload()
  )
  .do();

Java

// 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();

  API docs

Go

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

  API docs

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: Configure a schema
• 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
• Documentation feedback