Konfigurera tidsgräns i Azure Cosmos DB

2025-07-15

GÄLLER FÖR: NoSQL

I Azure Cosmos DB kan du välja att konfigurera time to live (TTL) på containernivå, eller så kan du åsidosätta det på objektnivå när du har angett TTL för containern. Du kan konfigurera TTL för en container med hjälp av Azure-portalen eller språkspecifika SDK:er. TTL-åsidosättningar på objektnivå kan konfigureras med hjälp av SDK:erna.

Tips/Råd

Den här artikelns innehåll är relaterat till TTL för Azure Cosmos DB-transaktionslager. Om du letar efter TTL för analyslagring, som möjliggör NoETL HTAP-scenarier via Azure Synapse Link, se Analytisk Time-to-Live.

Aktivera TTL i en container med hjälp av Azure-portalen

Använd följande steg för att aktivera TTL på en container utan förfallodatum. Om du aktiverar TTL på containernivå kan samma värde åsidosättas på en enskild objektnivå. Du kan också ange TTL genom att ange ett värde som inte är noll i sekunder.

Logga in på Azure-portalen.
Skapa ett nytt Azure Cosmos DB-konto eller välj ett befintligt konto.
Öppna fönstret Datautforskaren.
Välj en befintlig container, expandera fliken Inställningar och ändra följande värden:
1. Gå till Inställningar och leta upp Time to Live.
2. Baserat på dina behov kan du:
- Inaktivera den här inställningen.
- Ställ in den på På (inget standardvärde).
- Aktivera med ett TTL-värde som anges i sekunder.
1. Välj Spara för att spara ändringarna.

När DefaultTimeToLive är null är TTL av.
När DefaultTimeToLive är -1 är TTL-inställningen På (inget standardvärde).
När DefaultTimeToLive har något annat heltalsvärde (förutom 0) är TTL-inställningen På. Servern tar automatiskt bort objekt baserat på det konfigurerade värdet.

Aktivera TTL på en container med hjälp av Azure CLI eller Azure PowerShell

Information om hur du skapar eller aktiverar TTL för en container finns i:

Aktivera TTL på en container med hjälp av ett 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
)

db, _ := c.NewDatabase("demo_db")

pkDefinition := azcosmos.PartitionKeyDefinition{
	Paths: []string{"/state"},
	Kind:  azcosmos.PartitionKeyKindHash,
}

// Never expire by default
ttl := int32(-1)

db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID:                     "demo_container",
	PartitionKeyDefinition: pkDefinition,
	DefaultTimeToLive:      &ttl,
}, nil)

Ange TTL för en container med hjälp av ett SDK

Om du vill ange TTL för en container måste du ange ett icke-nollposalt tal som anger tidsperioden i sekunder. Baserat på det konfigurerade TTL-värde tas alla objekt i containern efter den senast ändrade tidsstämpeln för objektet _ts bort.

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
)

db, _ := c.NewDatabase("demo_db")

// Expire all documents after 90 days
ttl := int32(90 * 24 * 60 * 60)

db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID:                     containerName,
	PartitionKeyDefinition: pkDefinition,
	DefaultTimeToLive:      &ttl,
}, nil)

Ange TTL för ett objekt med hjälp av Azure-portalen

Förutom att ange en standard-TTL för en container kan du ange en TTL för ett objekt. Om du anger TTL på objektnivå åsidosätts standard-TTL för objektet i containern.

Om du vill ange TTL för ett objekt måste du ange ett positivt tal som är större än noll som anger perioden i sekunder som objektet ska gå ut efter den senaste ändrade tidsstämpeln för objektet _ts. Du kan även ange ett -1 när objektet inte ska upphöra att gälla.
Om objektet inte har något TTL-fält gäller TTL-värdet som standard för containern för objektet.
Om TTL är inaktiverat på containernivå ignoreras TTL-fältet på objektet tills TTL återaktiveras på containern.

Använd följande steg för att aktivera TTL för ett objekt:

Logga in på Azure-portalen.
Skapa ett nytt Azure Cosmos DB-konto eller välj ett befintligt konto.
Öppna fönstret Datautforskaren.
Välj en befintlig container, expandera den och ändra följande värden:
- Öppna fönstret Scale & Settings (Skalning och inställningar).
- Under Inställning letar du reda på Tid att leva.
- Välj På (inget standardvärde) eller välj På och ange ett TTL-värde.
- Välj Spara för att spara ändringarna.

Navigera till det objekt som du vill ange tid för att leva för, lägg till ttl egenskapen och välj Uppdatera.

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

Ange TTL för ett objekt med hjälp av ett 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)

custInfo := map[string]any{
	"id":    "SO05",
	"customerId": "CO18009186470",
	// Expire sales order in 30 days using "ttl" property
	"ttl": int32(60 * 60 * 24 * 30),
}

container, _ := db.NewContainer(containerName)

item, err := json.Marshal(custInfo)
container.CreateItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), item, nil)

Återställa TTL med hjälp av en SDK

Du kan återställa TTL för ett objekt genom att utföra en skriv- eller uppdateringsåtgärd på objektet. Skriv- eller uppdateringsåtgärden _ts anger den aktuella tiden och TTL för objektet som ska upphöra att gälla börjar igen. Om du vill ändra TTL-värdet för ett objekt kan du uppdatera fältet precis som du uppdaterar andra fält.

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
)

// Read the item
resp, _ := container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), "SO05", nil)

var order map[string]any
json.Unmarshal(resp.Value, &order)

// Update ttl to 2 hours
order["ttl"] = int32(120 * 60)
updatedOrder, err = json.Marshal(order)

container.ReplaceItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), "SO05", updatedOrder, nil)

Inaktivera TTL med hjälp av ett SDK

Om du vill inaktivera TTL på en container och stoppa bakgrundsprocessen från att söka efter objekt DefaultTimeToLive som har upphört att gälla, bör egenskapen på containern tas bort. Att ta bort den här egenskapen skiljer sig från att ange den till -1. När du anger till -1 kommer nya objekt som lagts till i containern att finnas för evigt, men du kan åsidosätta det här värdet för specifika objekt i containern. När du tar bort TTL-egenskapen från containern upphör objekten aldrig att gälla, även om de uttryckligen åsidosätter det tidigare TTL-standardvärdet.

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
)

containerInfo, _ := container.Read(context.Background(), nil)
props := containerInfo.ContainerProperties

// Disable ttl at container-level
props.DefaultTimeToLive = nil
container.Replace(context.Background(), *props, nil)

Time to Live i Azure Cosmos DB

Feedback

Var den här sidan till hjälp?