Collection Alias

An alias is a virtual collection name that points to a real collection. If you're familiar with symbolic links in Linux, it's very similar to that.

You can use an alias name, instead of the collection name, in any API call that uses a collection name. Typesense will internally resolve the alias to the collection name that the alias is configured to point to, and use that to perform the operation (searches, writes, etc).

Use Case

One common use-case for aliases is to reindex your data in the background on a new collection and then switch your application to it without any changes to your code.

Here's an example:

Let's say we have a collection called companies_june10 and an alias called companies pointing to that collection.

companies ---> companies_june10

In our application, for all search API calls we'll use the alias name companies, instead of using the collection name companies_june10:

shell

curl "http://localhost:8108/multi_search" \
        -X POST \
        -H "Content-Type: application/json" \
        -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
        -d '{
          "searches": [
            {
              "collection": "companies",
              "q": "Acme"
            }
          ]
        }'

Since companies is an alias, Typesense will resolve "collection": "companies" to companies_june10 internally, and perform the search against that collection.

On the next day (June 11), let's say we want to reindex our entire dataset. We can create a new collection called companies_june11 and start indexing the documents in the background into this collection.

When we are done indexing, if we updated the companies alias to now point to this new collection companies_june11, your application would immediately start sending searches to this freshly indexed collection, because we're using the alias name in the search query like above.

companies ---> companies_june11

Convenient, isn't it? Let's now look at how we can create, update and manage aliases.

Create or Update an alias

aliased_collection = {
  'collection_name': 'companies_june11'
}

// Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases().upsert('companies', aliased_collection)

</template> <template v-slot:PHP>

php

$aliasedCollection = [
  'collection_name' => 'companies_june11'
]

# Creates/updates an alias called `companies` to the `companies_june11` collection
$client->aliases->upsert('companies', $aliasedCollection)

</template> <template v-slot:Python>

aliased_collection = {
  'collection_name': 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)

</template> <template v-slot:Ruby>

aliased_collection = {
  'collection_name' => 'companies_june11'
}

# Creates/updates an alias called `companies` to the `companies_june11` collection
client.aliases.upsert('companies', aliased_collection)

</template> <template v-slot:Dart>

dart

final aliasedCollection = {
  'collection_name': 'companies_june11'
};

// Creates/updates an alias called `companies` to the `companies_june11` collection
await client.aliases.upsert('companies', aliased_collection);

</template> <template v-slot:Java>

java

CollectionAliasSchema collectionAlias = new CollectionAliasSchema();
collectionAlias.collectionName("companies_june11");

client.aliases().upsert("companies", collectionAlias);

</template> <template v-slot:Go>

aliasedCollection := &api.CollectionAliasSchema{
  CollectionName: "companies_june11",
}

// Creates/updates an alias called `companies` to the `companies_june11` collection
client.Aliases().Upsert(context.Background(), "companies", aliasedCollection)

</template> <template v-slot:Swift>

swift

let collection = CollectionAliasSchema(collectionName: "companies_june11")

// Creates/updates an alias called `companies` to the `companies_june11` collection
let (collectionAlias, response) = try await client.aliases().upsert(name: "companies", collection: collection)

</template> <template v-slot:Shell>

bash

curl "http://localhost:8108/aliases/companies" -X PUT \
    -H "Content-Type: application/json" \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
        "collection_name": "companies_june11"
    }'

</template> </Tabs>

Sample Response

json

{
  "name": "companies",
  "collection_name": "companies_june11",
}

</template> </Tabs>

Definition

PUT ${TYPESENSE_HOST}/aliases/:alias

Arguments

Parameter	Required	Description
collection_name	yes	Name of the collection you wish to map the alias to.

Retrieve an alias

We can find out which collection an alias points to by fetching it.

client.aliases('companies').retrieve()

</template> <template v-slot:PHP>

php

$client->aliases['companies']->retrieve()

</template> <template v-slot:Python>

client.aliases['companies'].retrieve()

</template> <template v-slot:Ruby>

client.aliases['companies'].retrieve

</template> <template v-slot:Dart>

dart

await client.alias('companies').retrieve();

</template> <template v-slot:Java>

java

CollectionAliasSchema collectionAlias = client.aliases("companies").retrieve();

</template> <template v-slot:Go>

client.Alias("companies").Retrieve(context.Background())

</template> <template v-slot:Swift>

swift

let (collectionAlias, response) = try await client.aliases().retrieve(name: "companies")

</template> <template v-slot:Shell>

bash

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    "http://localhost:8108/aliases/companies"

</template> </Tabs>

Sample Response

json

{
  "name": "companies",
  "collection_name": "companies_june11",
}

</template> </Tabs>

Definition

GET ${TYPESENSE_HOST}/aliases/:alias

List all aliases

List all aliases and the corresponding collections that they map to.

client.aliases().retrieve()

</template> <template v-slot:PHP>

php

$client->aliases->retrieve()

</template> <template v-slot:Python>

client.aliases.retrieve()

</template> <template v-slot:Ruby>

client.aliases.retrieve

</template> <template v-slot:Dart>

dart

await client.aliases.retrieve();

</template> <template v-slot:Java>

java

CollectionAliasesResponse collectionAliasesResponse = client.aliases().retrieve();

</template> <template v-slot:Go>

client.Aliases().Retrieve(context.Background())

</template> <template v-slot:Swift>

swift

let (collectionAliases, response) = try await client.aliases().retrieve()

</template> <template v-slot:Shell>

bash

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     "http://localhost:8108/aliases"

</template> </Tabs>

Sample Response

json

{
  "aliases": [
    {
      "name": "companies",
      "collection_name": "companies_june11"
    },
    {
      "name": "employees",
      "collection_name": "employees_june11"
    }
  ]
}

</template> </Tabs>

Definition

GET ${TYPESENSE_HOST}/aliases

Delete an alias

client.aliases('companies').delete()

</template> <template v-slot:PHP>

php

$client->aliases['companies']->delete()

</template> <template v-slot:Python>

client.aliases['companies'].delete()

</template> <template v-slot:Ruby>

client.aliases['companies'].delete

</template> <template v-slot:Dart>

dart

await client.alias('companies').delete();

</template> <template v-slot:Java>

java

CollectionAliasSchema collectionAlias = client.aliases("companies").delete();

</template> <template v-slot:Go>

client.Alias("companies").Delete(context.Background())

</template> <template v-slot:Swift>

swift

let (collectionAlias, response) = try await client.aliases().delete(name: "companies")

</template> <template v-slot:Shell>

bash

curl "http://localhost:8108/aliases/companies" -X DELETE
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

</template> </Tabs>

Sample Response

json

{
  "name": "companies",
  "collection_name": "companies_june11"
}

</template> </Tabs>

Definition

DELETE ${TYPESENSE_HOST}/aliases/:alias