Azure Cosmos DB에서 TTL(Time to Live) 구성

적용 대상: NoSQL

Azure Cosmos DB에서는 컨테이너 수준에서 TTL(Time to Live)을 구성하도록 선택하거나 컨테이너를 설정한 후 항목 수준에서 재정의할 수 있습니다. Azure Portal 또는 언어별 SDK를 사용하여 컨테이너에 대해 TTL을 구성할 수 있습니다. SDK를 사용하여 항목 수준 TTL 재정의를 구성할 수 있습니다.

이 문서의 내용은 Azure Cosmos DB 트랜잭션 저장소 TTL과 관련이 있습니다. Azure Synapse Link를 통해 NoETL HTAP 시나리오를 사용하도록 설정하는 분석 저장소 TTL을 찾고 있다면 여기를 클릭하세요.

Azure Portal을 사용하여 컨테이너에서 TTL 사용

컨테이너에서 만료 없이 TTL(Time to Live)을 사용하도록 설정하려면 다음 단계를 따르세요. 컨테이너 수준에서 TTL을 사용하도록 설정하여 개별 항목 수준에서 동일한 값을 재정의할 수 있습니다. 초의 값으로 0이 아닌 값을 입력하여 TTL을 설정할 수도 있습니다.

1. Azure Portal에 로그인합니다.

2. 새 Azure Cosmos DB 계정을 만들거나 기존 계정을 선택합니다.

3. 데이터 탐색기 창을 엽니다.

4. 기존 컨테이너를 선택하여 설정 탭을 확장하고, 다음 값을 수정합니다.

   • 설정 아래에서 TTL(Time to Live)을 찾습니다.

   • 요구 사항에 따라 다음을 수행할 수 있습니다.

     • 이 설정 끄기
     • 켜기(기본값 없음)로 설정 또는
     • 초 단위로 지정한 TTL 값으로 설정 켜기

   • 저장을 선택하여 변경 내용을 저장합니다.

   

• DefaultTimeToLive가 Null인 경우 TTL(Time to Live)이 꺼짐
• DefaultTimeToLive가 -1인 경우 TTL(Time to Live) 설정이 켜짐(기본값 없음)
• DefaultTimeToLive가 다른 Int 값(0 제외)을 가진 경우 TTL(Time to Live) 설정이 켜짐 서버는 구성된 값에 따라 항목을 자동으로 삭제합니다.

Azure CLI 또는 Azure PowerShell을 사용하여 컨테이너에서 TTL(Time to Live) 사용

컨테이너에서 TTL을 만들거나 사용하도록 설정하려면 다음을 참조하세요.

• Azure CLI를 사용하여 TTL이 설정된 컨테이너 만들기
• PowerShell을 사용하여 TTL이 설정된 컨테이너 만들기

SDK를 사용하여 컨테이너에서 TTL 사용

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

database = client.get_database_client('database')

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

SDK를 사용하여 컨테이너에서 TTL 설정

컨테이너에 대한 TTL(Time to Live)을 설정하려면 기간을 초 단위로 나타내는 0이 아닌 양수 값을 입력해야 합니다. 구성된 TTL 값에 따라, 컨테이너에 있는 모든 항목은 항목 _ts의 마지막으로 수정된 타임스탬프 후에 삭제됩니다.

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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
)

포털을 사용하여 항목의 TTL 설정

컨테이너에 대한 기본 TTL(Time to Live)을 설정하는 것 외에도 항목에 대한 TTL(Time to Live)을 설정할 수 있습니다. 항목 수준에서 TTL(Time to Live)을 설정하면 해당 컨테이너에 있는 항목의 기본 TTL이 재정의됩니다.

• 항목에 대한 TTL을 설정하려면 항목 _ts의 타임스탬프를 마지막으로 수정한 이후 항목을 만료할 기간(초)을 나타내는 0이 아닌 양수 값을 제공해야 합니다. 항목이 만료되지 않아야 할 때 -1도 제공할 수 있습니다.

• 항목에 TTL 필드에 없는 경우 기본적으로 컨테이너에 설정된 TTL이 항목에 적용됩니다.

• 컬렉션 수준에서 TTL이 설정되지 않으면 항목의 TTL 필드는 컨테이너에 대한 TTL이 다시 설정될 때까지 무시됩니다.

항목에 대해 TTL(Time to Live)을 사용하도록 설정하려면 다음 단계를 따르세요.

1. Azure Portal에 로그인합니다.

2. 새 Azure Cosmos DB 계정을 만들거나 기존 계정을 선택합니다.

3. 데이터 탐색기 창을 엽니다.

4. 기존 컨테이너를 선택하여 확장하고, 다음 값을 수정합니다.

   • 배율 및 설정 창을 엽니다.
   • 설정 아래에서 TTL(Time to Live)을 찾습니다.
   • 설정(기본값 없음)를 선택하거나 켜기를 선택하고 TTL 값을 설정합니다.
   • 저장을 선택하여 변경 내용을 저장합니다.

5. 다음으로, 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를 사용하여 항목의 TTL 설정

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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를 사용하여 TTL 다시 설정

항목에 대한 쓰기 또는 업데이트 작업을 수행하여 항목에 대한 TTL을 다시 설정할 수 있습니다. 쓰기 또는 업데이트 작업은 _ts를 현재 시간으로 설정하고, 항목이 만료되는 TTL이 다시 시작 됩니다. 항목의 TTL을 변경하려면 다른 필드를 업데이트하는 것처럼 필드를 업데이트하면 됩니다.

.NET SDK v3

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")    
);

Java SDK v4

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
);

Node SDK

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);

Python SDK

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를 사용하여 TTL 사용하지 않도록 설정

컨테이너에 대한 TTL(Time to Live)을 해제하고 백그라운드 프로세스에서 만료된 항목 검사를 중지하려면 컨테이너의 DefaultTimeToLive 속성을 삭제해야 합니다. 이 속성을 삭제하는 것은 -1로 설정하는 것과 다릅니다. -1로 설정하면 컨테이너에 추가되는 새 항목이 영구적으로 라이브 상태로 유지되지만 컨테이너의 특정 항목에서 이 값을 재정의할 수 있습니다. 컨테이너에서 TTL 속성을 제거하면 항목이 이전 기본 TTL 값을 명시적으로 재정의했더라도 항목이 절대 만료되지 않습니다.

.NET SDK v3

ContainerProperties properties = await container.ReadContainerAsync();

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

await container.ReplaceContainerAsync(properties);

Java SDK v4

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

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

container.replace(properties);

Node SDK

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

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

await container.replace(definition);

Python SDK

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

다음 단계

다음 문서에서 TTL(Time to Live)에 대해 자세히 알아보세요.

• TTL(Time to Live)