Configurar o Time to Live no Azure Cosmos DB

Artigo
01/10/2024

APLICA-SE A: NoSQL

No Azure Cosmos DB, você pode optar por configurar o TTL (Time to Live) no nível do contêiner ou substituí-lo em um nível de item após a configuração do contêiner. Pode configurar o TTL para um contentor através do portal do Azure ou de SDKS de linguagem específicos. As substituições de TTL de nível de item podem ser configuradas usando os SDKs.

O conteúdo deste artigo está relacionado ao repositório transacional TTL do Azure Cosmos DB. Se você estiver procurando por TTL de loja analisável, que permite cenários HTAP NoETL por meio do Azure Synapse Link, clique aqui.

Habilitar o tempo de vida em um contêiner usando o portal do Azure

Use as etapas a seguir para habilitar o tempo de vida em um contêiner sem validade. Habilitando 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 o TTL inserindo um valor diferente de zero por segundos.

Inicie sessão no portal do Azure.
Crie uma nova conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Explorador de Dados.
Selecione um contêiner existente, expanda a guia Configurações e modifique os seguintes valores:
- Em Configuração , localizar, Tempo de Viver.
- Com base na sua exigência, você pode:
  - Desativar esta definição
  - Defina-o como Ativado (sem padrão) ou
  - Ative com um valor TTL especificado em segundos.
- Selecione Guardar para guardar as alterações.

Quando DefaultTimeToLive é null, então seu Time to Live está desativado
Quando DefaultTimeToLive é -1, então, sua configuração Time to Live está On (Sem padrão)
Quando DefaultTimeToLive tiver qualquer outro valor Int (exceto 0), sua configuração Time to Live será On. O servidor excluirá automaticamente os itens com base no valor configurado.

Habilitar o tempo de vida em um contêiner usando a CLI do Azure ou o Azure PowerShell

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

Habilitar o tempo de vida 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 o tempo de vida em um contêiner usando um SDK

Para definir o tempo de vida em um contêiner, você precisa fornecer um número positivo diferente de zero que indique o período de tempo em segundos. Com base no valor TTL configurado, todos os itens no contêiner após o carimbo de data/hora da última modificação do item _ts sã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 tempo de vida em um item usando o Portal

Além de definir um tempo de vida padrão em um contêiner, você pode definir um tempo de vida para um item. Definir o tempo de vida no nível do item substituirá o TTL padrão do item nesse contêiner.

Para definir o TTL em um item, você precisa fornecer um número positivo diferente de zero, que indica o período, em segundos, para expirar o item após o carimbo de data/hora da última modificação do item _ts. Você também pode fornecer um -1 quando o item não deve expirar.
Se o item não tiver um campo TTL, então, por padrão, o TTL definido para o contêiner será aplicado ao item.
Se o TTL estiver desativado no nível do contêiner, o campo TTL no item será ignorado até que o TTL seja reativado no contêiner.

Use as seguintes etapas para habilitar o tempo de vida em um item:

Inicie sessão no portal do Azure.
Crie uma nova conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Explorador de Dados.
Selecione um contêiner existente, expanda-o e modifique os seguintes valores:
- Abra a janela Scale & Settings .
- Em Configuração , localizar, Tempo de Viver.
- Selecione Ativado (sem padrão) ou selecione Ativado e defina um valor TTL.
- Selecione Guardar para guardar as alterações.

Em seguida, navegue até o item para o qual você deseja definir o tempo de vida, adicione a ttl propriedade 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 o tempo de vida em 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 o tempo de vida usando um SDK

Você pode redefinir o tempo de vida em um item executando uma operação de gravação ou atualização no item. A operação de gravação ou atualização definirá a _ts hora atual e o TTL para o item expirar começará novamente. Se desejar alterar o TTL de um item, pode atualizar o campo tal como atualiza 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
)

Desativar o tempo de vida usando um SDK

Para desativar o tempo de vida em um contêiner e impedir que o processo em segundo plano verifique se há itens expirados, a DefaultTimeToLive propriedade no contêiner deve ser excluída. Excluir essa propriedade é diferente de defini-la como -1. Quando você o define como -1, os novos itens adicionados ao contêiner viverão para sempre, no entanto, você pode substituir esse valor em itens específicos no contêiner. Quando você remove a propriedade TTL do contêiner, os itens nunca expirarão, mesmo que tenham substituído explicitamente o valor 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óximos passos

Saiba mais sobre o tempo de vida no seguinte artigo:

Tempo de viver