Azure Cosmos DB で Time to Live を構成する

[アーティクル]
04/03/2023

適用対象: NoSQL

Azure Cosmos DB では、コンテナーレベルで Time to Live (TTL) の構成を選択することも、コンテナーでの設定後に項目レベルでそれをオーバーライドすることもできます。 Azure portal または言語固有の SDK を使用して、コンテナーの TTL を構成できます。項目レベルの TTL オーバーライドは、SDK を使用して構成できます。

この記事のコンテンツは Azure Cosmos DB トランザクションストア TTL に関連付けられています。 Azure Synapse Link 経由で NoETL HTAP シナリオを可能にする分析ストア TTL をお探しの場合、こちらをクリックしてください。

Azure portal を使用してコンテナーの Time to Live を有効にする

有効期限のないコンテナーの Time to Live を有効にするには、次の手順を使用します。コンテナーレベルで TTL を有効にし、個々の項目のレベルで同じ値をオーバーライドできるようにします。秒数として 0 以外の値を入力して TTL を設定することもできます。

Azure portal にサインインします。
新しい Azure Cosmos DB アカウントを作成するか、既存のアカウントを選びます。
[データエクスプローラー] ウィンドウを開きます。
既存のコンテナーを選択し、[設定] タブ展開して以下の値を変更します。
- [設定] で [Time to Live] を探します。
- 要件に基づいて、次を行えます。
  - この設定をオフにする
  - オン (既定値なし) に設定する
  - 秒単位で指定された TTL 値で [オン] に切り替える
- [保存] を選択して変更を保存します。

DefaultTimeToLive が null の場合、Time to Live はオフになります
DefaultTimeToLive が -1 の場合、Time to Live の設定はオン (既定値なし) になります
DefaultTimeToLive が他の整数値 (0 を除く) の場合、Time to Live の設定はオンになります。サーバーにより、構成された値に基づいて項目が自動的に削除されます。

Azure CLI または Azure PowerShell を使用してコンテナーの Time to Live を有効にする

コンテナーで TTL を作成または有効にするには、以下を参照してください。

SDK を使用してコンテナーの Time to Live を有効にする

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
)

SDK を使用してコンテナーの Time to Live を設定する

コンテナーの Time to Live を設定するには、秒単位で期間を示す 0 以外の正の数を指定する必要があります。構成された TTL 値に基づいて、項目 _ts の最終変更タイムスタンプより後のコンテナー内の項目はすべて削除されます。

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
)

Portal を使用して項目の有効期限を設定する

コンテナーに既定の Time to Live を設定するだけでなく、項目の Time to Live を設定することもできます。項目レベルで Time to Live を設定すると、そのコンテナーに含まれている項目の既定の TTL がオーバーライドされます。

項目に対して TTL を設定するには、項目 _ts の最終変更タイムスタンプの後に項目が期限切れになるように、期間 (秒単位) を示す 0 以外の正の数を指定する必要があります。項目が期限切れになってはならないときは、-1 も指定できます。
項目に TTL フィールドがない場合、既定では、コンテナーに設定された TTL が項目に適用されます。
TTL がコンテナーレベルで無効になっている場合、TTL がコンテナーで再び有効になるまで、項目の TTL フィールドは無視されます。

項目に対して Time to Live を有効にするには、次の手順を使用します。

Azure portal にサインインします。
新しい Azure Cosmos DB アカウントを作成するか、既存のアカウントを選びます。
[データエクスプローラー] ウィンドウを開きます。
既存のコンテナーを選択し、展開して以下の値を変更します。
- [Scale & Settings]\(スケールと設定\) ウィンドウを開きます。
- [設定] で [Time to Live] を探します。
- [オン (既定値なし)] または [オン] を選択し、TTL 値を設定します。
- [保存] を選択して変更を保存します。

次に、Time to Live を設定する項目に移動し、ttl プロパティを追加して [更新] を選択します。

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

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)

SDK を使用して有効期限をリセットする

項目に対して書き込みまたは更新の操作を実行することにより、項目の Time to Live をリセットできます。書き込みまたは更新の操作を行うと、_ts が現在の時刻に設定され、項目が期限切れになる TTL が再び開始されます。項目の TTL を変更したい場合は、他のフィールドを更新する場合と同じように、このフィールドを更新できます。

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
)

SDK を使用して有効期限を無効にする

コンテナーの Time to Live を無効にし、バックグラウンドプロセスによる期限切れ項目の確認を停止するには、コンテナーの DefaultTimeToLive プロパティを削除する必要があります。このプロパティの削除は、-1 に設定することとは異なります。 -1 に設定した場合は、コンテナーに追加される新しい項目が無期限になりますが、コンテナーに含まれている特定の項目についてこの値をオーバーライドできます。コンテナーから TTL プロパティを削除した場合、項目は、以前の既定の TTL 値を明示的にオーバーライドしていても、期限切れになることはありません。

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
)

次のステップ

Time to Live の詳細について、以下の記事で学習します。

Time to Live