Configurar a vida útil no Azure Cosmos DB

Artigo
04/03/2023

APLICA-SE A: NoSQL

No Azure Cosmos DB, você pode optar por configurar a TTL (vida útil) no nível do contêiner ou substituí-la no nível de um item após a definição do contêiner. Você pode configurar a TTL para um contêiner usando o portal do Azure ou os SDKs específicos da linguagem. As substituições de TTL no nível do item podem ser configuradas usando os SDKs.

O conteúdo desde artigo está relacionado ao TTL do repositório transacional do Azure Cosmos DB. Se você estiver procurando por TTL do repositório analítico, que habilita cenários NoETL HTAP por meio do link Synapse do Azure, clique aqui.

Habilitar vida útil em um contêiner usando o portal do Azure

Use as etapas a seguir para habilitar a vida útil de um contêiner sem prazo de expiração. Habilite o TTL no nível do contêiner para permitir que o mesmo valor seja substituído no nível de um item individual. Você também pode definir a TTL inserindo um valor diferente de zero para os segundos.

Entre no portal do Azure.
Crie uma conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Data Explorer.
Selecione um contêiner existente, expanda a guia Configurações e modifique os valores a seguir:
- Em Configuração, localize Vida Útil.
- Com base no requisito, você pode:
  - Desativar esta configuração
  - Defini-la como On (sem padrão) ou
  - Ativar com um valor TTL especificado em segundos.
- Selecione Salvar para salvar as alterações.

Quando DefaultTimeToLive é nulo, sua vida útil está desativada
Quando DefaultTimeToLive é -1, sua configuração de vida útil está ativada (não padrão)
Quando DefaultTimeToLive tem qualquer outro valor inteiro (exceto 0), a configuração de vida útil está ativada. O servidor excluirá automaticamente itens com base no valor configurado.

Habilitar vida útil em um contêiner usando o CLI do Azure ou Azure PowerShell

Para criar ou habilitar TTL em um contêiner, consulte

Habilitar vida útil em um contêiner usando um SDK

Database database = client.GetDatabase("database");

ContainerProperties properties = new ()
{
    Id = "container",
    PartitionKeyPath = "/customerId",
    // Never expire by default
    DefaultTimeToLive = -1
};

// Create a new container with TTL enabled and without any expiration value
Container container = await database
    .CreateContainerAsync(properties);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Never expire by default
properties.setDefaultTimeToLiveInSeconds(-1);

// Create a new container with TTL enabled and without any expiration value
CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Never expire by default
    defaultTtl: -1
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Never expire by default
    default_ttl=-1
)

Definir a vida útil em um contêiner usando um SDK

Para definir a vida útil de um contêiner, você precisará fornecer um número positivo diferente de zero que indica o período de tempo em segundos. Com base no valor de TTL configurado, todos os itens no contêiner após a última modificação do carimbo de hora do item _ts serão excluídos.

Database database = client.GetDatabase("database");

ContainerProperties properties = new ()
{
    Id = "container",
    PartitionKeyPath = "/customerId",
    // Expire all documents after 90 days
    DefaultTimeToLive = 90 * 60 * 60 * 24
};

// Create a new container with TTL enabled and without any expiration value
Container container = await database
    .CreateContainerAsync(properties);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Expire all documents after 90 days
properties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);

CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Expire all documents after 90 days
    defaultTtl: 90 * 60 * 60 * 24
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Expire all documents after 90 days
    default_ttl=90 * 60 * 60 * 24
)

Definir a vida útil de um item usando o portal

Além de definir uma vida útil padrão de um contêiner, você pode definir a vida útil de um item. A definição da vida útil no nível do item substituirá a TTL padrão do item no contêiner.

Para definir a TTL em um item, é necessário fornecer um número positivo diferente de zero que indique o período, em segundos, em que o item expira após a modificação de seu último carimbo de data/hora (_ts). Você também pode fornecer um -1 quando o item não deve expirar.
Se o item não tiver um campo TTL, por padrão, a TTL definida para o contêiner será aplicada ao item.
Se a TTL estiver desabilitada no nível do contêiner, o campo TTL no item será ignorado até que a TTL seja habilitada novamente no contêiner.

Use as etapas a seguir para habilitar a vida útil de um item:

Entre no portal do Azure.
Crie uma conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Data Explorer.
Selecione um contêiner existente, expanda-o e modifique os valores abaixo:
- Abra a janela Escala e Configurações.
- Em Configuração, localize Vida Útil.
- Selecione Ativado (não há padrão) ou selecione Ativado e defina um valor de vida útil.
- Selecione Salvar para salvar as alterações.

Em seguida, navegue até o item para o qual você deseja definir a vida útil, adicione a propriedade ttl e selecione Atualizar.

{
    "id": "1",
    "_rid": "Jic9ANWdO-EFAAAAAAAAAA==",
    "_self": "dbs/Jic9AA==/colls/Jic9ANWdO-E=/docs/Jic9ANWdO-EFAAAAAAAAAA==/",
    "_etag": "\"0d00b23f-0000-0000-0000-5c7712e80000\"",
    "_attachments": "attachments/",
    "ttl": 10,
    "_ts": 1551307496
}

Definir a vida útil de um item usando um SDK

public record SalesOrder(string id, string customerId, int ttl);

Container container = database.GetContainer("container");

SalesOrder item = new (
    "SO05", 
    "CO18009186470"
    // Expire sales order in 30 days using "ttl" property
    ttl:  60 * 60 * 24 * 30
);

await container.CreateItemAsync<SalesOrder>(item);

public class SalesOrder {

    public String id;

    public String customerId;

    // Include a property that serializes to "ttl" in JSON
    public Integer ttl;

}

CosmosContainer container = database.getContainer("container");

SalesOrder item = new SalesOrder();
item.id = "SO05";
item.customerId = "CO18009186470";
// Expire sales order in 30 days using "ttl" property
item.ttl = 60 * 60 * 24 * 30;

container.createItem(item);

const container = await database.container("container");

const item = {
    id: 'SO05',
    customerId: 'CO18009186470',
    // Expire sales order in 30 days using "ttl" property
    ttl: 60 * 60 * 24 * 30
};

await container.items.create(item);

container = database.get_container_client('container')

item = {
    'id': 'SO05',
    'customerId': 'CO18009186470',
    # Expire sales order in 30 days using "ttl" property
    'ttl': 60 * 60 * 24 * 30
}

container.create_item(body=item)

Redefinir a vida útil usando um SDK

Você pode redefinir a vida útil de um item executando uma operação de gravação ou atualização no item. A operação de gravação ou atualização definirá o _ts como a hora atual, e a TTL até que o item expire será iniciada novamente. Se você quiser alterar a TTL de um item, poderá atualizar o campo exatamente como atualizaria qualquer outro campo.

SalesOrder item = await container.ReadItemAsync<SalesOrder>(
    "SO05", 
    new PartitionKey("CO18009186470")
);

// Update ttl to 2 hours
SalesOrder modifiedItem = item with { 
    ttl = 60 * 60 * 2 
};

await container.ReplaceItemAsync<SalesOrder>(
    modifiedItem,
    "SO05", 
    new PartitionKey("CO18009186470")    
);

CosmosItemResponse<SalesOrder> response = container.readItem(
    "SO05", 
    new PartitionKey("CO18009186470"),
    SalesOrder.class
);

SalesOrder item = response.getItem();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

CosmosItemRequestOptions options = new CosmosItemRequestOptions();
container.replaceItem(
    item,
    "SO05", 
    new PartitionKey("CO18009186470"),
    options
);

const { resource: item } = await container.item(
    'SO05',
    'CO18009186470'
).read();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

await container.item(
    'SO05',
    'CO18009186470'
).replace(item);

item = container.read_item(
    item='SO05',
    partition_key='CO18009186470'
)

# Update ttl to 2 hours
item['ttl'] = 60 * 60 * 2 

container.replace_item(
    item='SO05',
    body=item
)

Desabilitar a vida útil usando um SDK

Para desabilitar a vida útil de um contêiner e interromper o processo em segundo plano de verificação de itens expirados, a DefaultTimeToLive no contêiner deve ser excluída. A exclusão dessa propriedade é diferente de defini-la como -1. Quando você a define como -1, novos itens adicionados ao contêiner terão vida útil eterna; no entanto, você pode substituir esse valor em itens específicos no contêiner. Quando você remover a propriedade de TTL do contêiner, os itens nunca expirarão, mesmo se tiverem substituído explicitamente o valor de TTL padrão anterior.

ContainerProperties properties = await container.ReadContainerAsync();

// Disable ttl at container-level
properties.DefaultTimeToLive = null;

await container.ReplaceContainerAsync(properties);

CosmosContainerResponse response = container.read();
CosmosContainerProperties properties = response.getProperties();

// Disable ttl at container-level
properties.setDefaultTimeToLiveInSeconds(null);

container.replace(properties);

const { resource: definition } = await container.read();

// Disable ttl at container-level
definition.defaultTtl = null;

await container.replace(definition);

database.replace_container(
    container,
    partition_key=PartitionKey(path='/id'),
    # Disable ttl at container-level
    default_ttl=None
)

Próximas etapas

Saiba mais sobre vida útil no seguinte artigo:

Vida útil