:::callout{intent="info" title="Added in `v1.32`"}
:::

Collection aliases allow you to create alternative names for your collections. This is useful for migrating between collections without downtime, A/B testing, or providing more convenient names for collections. An alias acts as a reference to a collection - when you query and manage objects using an alias name, Weaviate automatically routes the request to the target collection.

:::callout{intent="info" title="Collection alias usage"}
Weaviate automatically routes alias requests to the target collection for **object-related operations**. You can use aliases wherever collection names are required for:

- **[Managing objects](../how-to-manage-objects/index.md)**: [Create](../how-to-manage-objects/create.md), [batch import](../how-to-manage-objects/import.md), [read](../how-to-manage-objects/read.md), [update](../how-to-manage-objects/update.md) and [delete](../how-to-manage-objects/delete.md) objects through collection aliases.
- **[Querying objects](../how-to-query-search/index.md)**: [Fetch](../how-to-query-search/basics.md) objects and perform searches ([vector](../how-to-query-search/similarity.md), [keyword](../how-to-query-search/bm25.md), [hybrid](../how-to-query-search/hybrid.md), [image](../how-to-query-search/image.md), [generative/RAG](../how-to-query-search/generative.md)) and [aggregations](../how-to-query-search/aggregate.md) through aliases.
:::

## Create an alias

To create an alias, specify the alias name and the target collection it should point to.

:::code-group{sync="languages"}
```python title="Python"
# Create a collection first
client.collections.create(
    name="Articles",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ],
)

# Create an alias pointing to the collection
client.alias.create(alias_name="ArticlesAlias", target_collection="Articles")
```

```typescript title="JavaScript/TypeScript"
// Create a collection first
await client.collections.create({
    name: "Articles",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
    ],
})

console.log('Created collection "Articles"')
// Create an alias pointing to the collection
await client.alias.create({
    alias: "ArticlesAlias",
    collection: "Articles"
})

console.log('Created alias "ArticlesAlias"')
```

```go title="Go"
// Create a collection first
err := client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "Articles",
  Vectorizer: "none",
  Properties: []*models.Property{
    {Name: "title", DataType: schema.DataTypeText.PropString()},
    {Name: "content", DataType: schema.DataTypeText.PropString()},
  },
}).Do(ctx)

require.NoError(t, err)

// Create an alias pointing to the collection
err = client.Alias().AliasCreator().WithAlias(&alias.Alias{
  Alias: "ArticlesProd",
  Class: "Articles",
}).Do(ctx)
```

```java title="Java"
// Create a collection first
client.collections.create("Articles", col -> col.vectorConfig(VectorConfig.selfProvided())
    .properties(Property.text("title"), Property.text("content")));

// Create an alias pointing to the collection
client.alias.create("Articles", "ArticlesAlias");
```

```csharp title="C#"
// Create a collection first
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = Articles,
        VectorConfig = Configure.Vector("default", v => v.SelfProvided()),
        Properties = [Property.Text("title"), Property.Text("content")],
    }
);

// Create an alias pointing to the collection
await client.Alias.Create(ArticlesAlias, Articles);
```
:::

:::callout{intent="note"}
- An alias name must be unique and cannot match any existing collection or alias name
- Multiple aliases can point to the same collection
- Aliases can only be used instead of collection names in object-related operations (managing objects and querying)
:::

## List all aliases

Retrieve all aliases in your Weaviate instance.

:::code-group{sync="languages"}
```python title="Python"
# Get all aliases in the instance
all_aliases = client.alias.list_all()

for alias_name, alias_info in all_aliases.items():
    print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")
```

```typescript title="JavaScript/TypeScript"
// Get all aliases in the instance
const allAliases = await client.alias.listAll()

if (allAliases) {
    for (const [_, aliasInfo] of Object.entries(allAliases)) {
        console.log(`Alias: ${aliasInfo.alias} -> Collection: ${aliasInfo.collection}`);
    }
}
```

```go title="Go"
// Get all aliases in the instance
allAliases, err := client.Alias().Getter().Do(ctx)

require.NoError(t, err)

// Filter to show only aliases from this example
for _, aliasInfo := range allAliases {
  if aliasInfo.Class == "Articles" || aliasInfo.Class == "ArticlesV2" {
    fmt.Printf("Alias: %s -> Collection: %s\n", aliasInfo.Alias, aliasInfo.Class)
  }
}
```

```java title="Java"
// Get all aliases in the instance
List<Alias> allAliases = client.alias.list();

for (Alias aliasInfo : allAliases) {
  System.out.printf("Alias: %s -> Collection: %s\n", aliasInfo.alias(), aliasInfo.collection());
}
```

```csharp title="C#"
// Get all aliases in the instance
var allAliases = await client.Alias.List();

foreach (var entry in allAliases)
{
    Console.WriteLine($"Alias: {entry.Name} -> Collection: {entry.TargetCollection}");
}
```
:::

## List aliases for a specific collection

Get all aliases that point to a specific collection.

:::code-group{sync="languages"}
```python title="Python"
# Get all aliases pointing to a specific collection
collection_aliases = client.alias.list_all(collection="Articles")

for alias_name, alias_info in collection_aliases.items():
    print(f"Alias pointing to Articles: {alias_info.alias}")
```

```typescript title="JavaScript/TypeScript"
// Get all aliases pointing to a specific collection
const collectionAliases = await client.alias.listAll({ collection: "Articles" })

if (collectionAliases) {
    for (const [_, aliasInfo] of Object.entries(collectionAliases)) {
        console.log(`Alias pointing to Articles: ${aliasInfo.alias}`);
    }
}
```

```go title="Go"
// Get all aliases pointing to a specific collection
collectionAliases, err := client.Alias().Getter().WithClassName("Articles").Do(ctx)

require.NoError(t, err)

for _, aliasInfo := range collectionAliases {
  fmt.Printf("Alias pointing to Articles: %s\n", aliasInfo.Alias)
}
```

```java title="Java"
// Get all aliases pointing to a specific collection
List<Alias> collectionAliases = client.alias.list(a -> a.collection("Articles"));

for (Alias aliasInfo : collectionAliases) {
  System.out.printf("Alias pointing to Articles: %s\n", aliasInfo.alias());
}
```

```csharp title="C#"
// Get all aliases pointing to a specific collection
var collectionAliases = await client.Alias.List(Articles);

foreach (var entry in collectionAliases)
{
    Console.WriteLine($"Alias pointing to Articles: {entry.Name}");
}
```
:::

## Get alias details

Retrieve information about a specific alias.

:::code-group{sync="languages"}
```python title="Python"
# Get information about a specific alias
alias_info = client.alias.get(alias_name="ArticlesAlias")

if alias_info:
    print(f"Alias: {alias_info.alias}")
    print(f"Target collection: {alias_info.collection}")
```

```typescript title="JavaScript/TypeScript"
// Get information about a specific alias
const aliasInfo = await client.alias.get("ArticlesAlias")

if (aliasInfo) {
    console.log(`Alias: ${aliasInfo.alias}`);
    console.log(`Target collection: ${aliasInfo.collection}`);
}
```

```go title="Go"
// Get information about a specific alias
aliasInfo, err := client.Alias().AliasGetter().WithAliasName("ArticlesProd").Do(ctx)

require.NoError(t, err)

if aliasInfo != nil {
  fmt.Printf("Alias: %s\n", aliasInfo.Alias)
  fmt.Printf("Target collection: %s\n", aliasInfo.Class)
}
```

```java title="Java"
// Get information about a specific alias
Optional<Alias> aliasInfoOpt = client.alias.get("ArticlesAlias");

aliasInfoOpt.ifPresent(aliasInfo -> {
  System.out.printf("Alias: %s\n", aliasInfo.alias());
  System.out.printf("Target collection: %s\n", aliasInfo.collection());
});
```

```csharp title="C#"
// Get information about a specific alias
var aliasInfo = await client.Alias.Get(aliasName: ArticlesAlias);

if (aliasInfo != null)
{
    Console.WriteLine($"Alias: {aliasInfo.Name}");
    Console.WriteLine($"Target collection: {aliasInfo.TargetCollection}");
}
```
:::

## Update an alias

Change the target collection that an alias points to. This operation is atomic and provides instant switching between collections.

:::code-group{sync="languages"}
```python title="Python"
# Create a new collection for migration
client.collections.create(
    name="ArticlesV2",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(
            name="author", data_type=wvc.config.DataType.TEXT
        ),  # New field
    ],
)

# Update the alias to point to the new collection
success = client.alias.update(
    alias_name="ArticlesAlias", new_target_collection="ArticlesV2"
)

if success:
    print("Alias updated successfully")
```

```typescript title="JavaScript/TypeScript"
// Create a new collection for migration
await client.collections.create({
    name: "ArticlesV2",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
        { name: "author", dataType: weaviate.configure.dataType.TEXT },  // New field
    ],
})

// Update the alias to point to the new collection
await client.alias.update({
    alias: "ArticlesAlias",
    newTargetCollection: "ArticlesV2"
})

console.log("Alias updated successfully")
```

```go title="Go"
// Create a new collection for migration
err := client.Schema().ClassCreator().WithClass(&models.Class{
  Class:      "ArticlesV2",
  Vectorizer: "none",
  Properties: []*models.Property{
    {Name: "title", DataType: schema.DataTypeText.PropString()},
    {Name: "content", DataType: schema.DataTypeText.PropString()},
    {Name: "author", DataType: schema.DataTypeText.PropString()}, // New field
  },
}).Do(ctx)

require.NoError(t, err)

// Update the alias to point to the new collection
err = client.Alias().AliasUpdater().WithAlias(&alias.Alias{
  Alias: "ArticlesProd",
  Class: "ArticlesV2",
}).Do(ctx)

if err == nil {
  fmt.Println("Alias updated successfully")
}
```

```java title="Java"
// Create a new collection for migration
client.collections.create("ArticlesV2", col -> col.vectorConfig(VectorConfig.selfProvided())
    .properties(Property.text("title"), Property.text("content"), Property.text("author") // New field
    ));

// Update the alias to point to the new collection
client.alias.update("ArticlesAlias", "ArticlesV2");
```

```csharp title="C#"
// Create a new collection for migration
await client.Collections.Create(
    new CollectionCreateParams
    {
        Name = ArticlesV2,
        VectorConfig = Configure.Vector("default", v => v.Text2VecTransformers()),
        Properties =
        [
            Property.Text("title"),
            Property.Text("content"),
            Property.Text("author"), // New field
        ],
    }
);

// Update the alias to point to the new collection
bool success =
    (await client.Alias.Update(aliasName: ArticlesAlias, targetCollection: ArticlesV2))
    != null;

if (success)
{
    Console.WriteLine("Alias updated successfully");
}
```
:::

:::callout{intent="tip" title="Use case: Zero-downtime migration"}
Updating an alias is particularly useful for migrations:

1. Create a new collection with updated collection definition
2. Import data into the new collection
3. Update the alias to point to the new collection
4. Continue to use the alias - all queries to it are now directed to the new collection

For a code example on how to perform migrations, visit the [Tutorial: Migrating collections with aliases](../guides-tutorials/collection-aliases.md)
:::

## Delete an alias

Remove an alias. This only deletes the alias pointer, not the underlying collection.

:::code-group{sync="languages"}
```python title="Python"
# Delete an alias (the underlying collection remains)
client.alias.delete(alias_name="ArticlesAlias")
```

```typescript title="JavaScript/TypeScript"
// Delete an alias (the underlying collection remains)
await client.alias.delete("ArticlesAlias")
```

```go title="Go"
// Delete an alias (the underlying collection remains)
err = client.Alias().AliasDeleter().WithAliasName("ArticlesProd").Do(ctx)
```

```java title="Java"
// Delete an alias (the underlying collection remains)
client.alias.delete("ArticlesAlias");
```

```csharp title="C#"
// Delete an alias (the underlying collection remains)
await client.Alias.Delete(aliasName: ArticlesAlias);
```
:::

:::callout{intent="note"}
- Deleting a collection does not automatically delete aliases pointing to it
:::

## Using aliases in operations

Once created, aliases can be used instead of collection names in all object-related operations, like data import and querying.

:::code-group{sync="languages"}
```python title="Python"
# Ensure the Articles collection exists (it might have been deleted in previous examples)

client.collections.create(
    name="Articles",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ],
)
```

```typescript title="JavaScript/TypeScript"
// Ensure the Articles collection exists (it might have been deleted in previous examples)

await client.collections.create({
    name: "Articles",
    vectorizers: weaviate.configure.vectors.selfProvided(),
    properties: [
        { name: "title", dataType: weaviate.configure.dataType.TEXT },
        { name: "content", dataType: weaviate.configure.dataType.TEXT },
    ],
})
```

```go title="Go"
// Create an alias for easier access
err := client.Alias().AliasCreator().WithAlias(&alias.Alias{
  Alias: "MyArticles",
  Class: "Articles",
}).Do(ctx)

require.NoError(t, err)

// Use the alias just like a collection name

// Insert data using the alias
w, err := client.Data().Creator().
  WithClassName("MyArticles").
  WithProperties(map[string]interface{}{
    "title":   "Using Aliases in Weaviate",
    "content": "Aliases make collection management easier...",
  }).Do(ctx)

require.NoError(t, err)

// Query using the alias
result, err := client.Data().ObjectsGetter().
  WithClassName("MyArticles").
  WithLimit(5).
  Do(ctx)

require.NoError(t, err)

for _, obj := range result {
  if title, ok := obj.Properties.(map[string]interface{})["title"]; ok {
    fmt.Printf("Found: %v\n", title)
  }
}
```

```java title="Java"
// Use the alias just like a collection name
CollectionHandle<Map<String, Object>> articles = client.collections.use("ArticlesAlias");

// Insert data using the alias
articles.data.insert(Map.of("title", "Using Aliases in Weaviate", "content",
    "Aliases make collection management easier..."));

// Query using the alias
var results = articles.query.fetchObjects(q -> q.limit(5));

for (var obj : results.objects()) {
  System.out.printf("Found: %s\n", obj.properties().get("title"));
}
```

```csharp title="C#"
// Ensure the Articles collection exists (it might have been deleted in previous examples)
// Note: In C# we check existence first to avoid errors if it already exists
if (!await client.Collections.Exists(Articles))
{
    await client.Collections.Create(
        new CollectionCreateParams
        {
            Name = Articles,
            VectorConfig = Configure.Vector("default", v => v.SelfProvided()),
            Properties = [Property.Text("title"), Property.Text("content")],
        }
    );
}
```
:::

## Further resources

- [Manage collections: Basic operations](collection-operations.md)
- [References: Collection definition](../reference-configuration/collections.md)
- [API References: REST: Aliases](/weaviate/api/rest#tag/aliases)

## Questions and feedback

Have a question or feedback? Here's how to reach us.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.