---
title: InsertBuilder
summary: A builder for KVStore insertions, supporting advanced configuration like InsertMode, backgroundfetch, ifgeneration_match, metadata, ttl, and asynchronous execution.
url: https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/struct.InsertBuilder/
---

**Kind:** Struct  
**Module:** [fastly](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/)  
**Package:** fastly 0.13.1  
**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#265

```rust
pub struct InsertBuilder<'a> { /* private fields */ }
```

A builder for KVStore insertions, supporting advanced configuration like [`InsertMode`](https://docs.rs/fastly_sys/latest/fastly_sys/enum.InsertMode.html), background_fetch, if_generation_match, metadata, ttl, and asynchronous execution.

```rust
store.build_insert()
   .mode(InsertMode::Prepend)
   .background_fetch()
   .if_generation_match(1337)
   .metadata("2000B of arbitrary data")
   .time_to_live(std::time::Duration::from_secs(5))
   .execute("key1", "value1")?;
```

## Synchronous and Asynchronous support

InsertBuilder also exposes the ability to issue an asynchronous insert. When finalizing the InsertBuilder,
[`execute_async`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/kv_store/struct.InsertBuilder/#method-execute_async) will send the request, and unblock. There is currently no polling mechanism.
To retrieve the result, use the blocking function [`pending_insert_wait`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/kv_store/struct.KVStore/#method-pending_insert_wait).

## Examples

```rust
// synchronous non-builder insert
let result: Result<(), KVStoreError> = store.insert("key", "value");
// synchronous builder insert
let result: Result<(), KVStoreError> = store.build_insert().execute("key", "value");
// asynchronous builder insert
let insert_handle: Result<PendingInsertHandle, KVStoreError> = store.build_insert().execute_async("key", "value");
let result: Result<(), KVStoreError> = store.pending_insert_wait(insert_handle?);
```

## Methods

### background_fetch

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#281

```rust
fn background_fetch(self) -> Self
```

If set, allows fetching from the origin to occur in the background, enabling a faster response with stale content. The cache will be updated with fresh content after the request is completed.

**Parameters**

- `self`: `Self`

**Returns**

`Self`

### execute

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#315

```rust
fn execute(self, key: &str, value: impl Into<Body>) -> Result<(), KVStoreError>
```

Initiate and wait on an insert of a value into the KV Store.

Returns `Ok(())` if the value is inserted, and `KVStoreError` if the insert failed.

**Parameters**

- `self`: `Self`
- `key`: `&str`
- `value`: `impl Into<Body>`

**Returns**

`Result<(), KVStoreError>`

### execute_async

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#331

```rust
fn execute_async(&self, key: &str, value: impl Into<Body>) -> Result<PendingInsertHandle, KVStoreError>
```

Initiate async insert of a value into the KV Store.

Returns `Ok(Some(PendingInsertHandle))` if insert creation is successful.

**Parameters**

- `self`: `&Self`
- `key`: `&str`
- `value`: `impl Into<Body>`

**Returns**

`Result<PendingInsertHandle, KVStoreError>`

### if_generation_match

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#289

```rust
fn if_generation_match(self, gen: u64) -> Self
```

Requests for keys will return a 'generation' header specific to the version of a key. The generation header is a unique, non-serial 64-bit unsigned integer that can be used for testing against a specific KV store value.

**Parameters**

- `self`: `Self`
- `gen`: `u64`

**Returns**

`Self`

### metadata

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#297

```rust
fn metadata(self, data: &str) -> Self
```

Sets an arbitrary data field which can contain up to 2000B of data.

**Parameters**

- `self`: `Self`
- `data`: `&str`

**Returns**

`Self`

### mode

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#276

```rust
fn mode(self, mode: InsertMode) -> Self
```

Change the behavior in the case when the new key matches an existing key.

**Parameters**

- `self`: `Self`
- `mode`: `InsertMode`

**Returns**

`Self`

### time_to_live

**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/kv_store.rs#305

```rust
fn time_to_live(self, ttl: Duration) -> Self
```

Sets a time for the key to expire. Deletion will take place up to 24 hours after the ttl reaches 0.

**Parameters**

- `self`: `Self`
- `ttl`: `std::time::Duration`

**Returns**

`Self`

## Auto trait implementations

- `Freeze`
- `RefUnwindSafe`
- `Send`
- `Sync`
- `Unpin`
- `UnsafeUnpin`
- `UnwindSafe`

## Blanket implementations

- `Any`
- `Borrow<T>`
- `BorrowMut<T>`
- `Downcast`
- `DowncastSync`
- `ErasedDestructor`
- `From<T>`
- `Into<U>`
- `IntoEither`
- `Same`
- `TryFrom<U>`
- `TryInto<U>`