---
title: replace
summary: Returns a ReplaceBuilder that will perform a transactional cache replacement.
url: https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/fn.replace/
---

**Kind:** Function  
**Module:** [core](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/)  
**Package:** fastly 0.13.1  
**Source:** https://docs.rs/crate/fastly/0.13.1/source/src/cache/core/replace.rs#111

```rust
fn replace(key: CacheKey) -> ReplaceBuilder
```

Returns a [`ReplaceBuilder`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/) that will perform a transactional cache replacement.

```rust
let current = replace(CacheKey::from_static(b"my_key")).begin()?;

let contents = if let Some(found) = current.existing_object() {
    todo!("create replacement object from existing")
} else {
    b"my cached object"
};

let mut writer = current
    .surrogate_keys(["my_key"])
    .known_length(contents.len() as u64)
    .execute(Duration::from_secs(3600))?;
writer.write_all(contents)?;
writer.finish()?;
```

A cache replacement has two phases.  In the first phase following [`ReplaceBuilder::begin()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/#method-begin)
you have access to an existing object, if one exists, including its metadata.  In the second
phase following [`Replace::execute()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Replace/#method-execute) you write the replacement object.  You may use the
existing object from the first phase to determine the metadata arguments for the replacement
object.

The [`ReplaceStrategy`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/enum.ReplaceStrategy/) chosen controls whether one replace will wait for another and whether
or not a lookup request needs to wait for a the replace to start writing the replacement
object.

When replacing an object the request headers used to lookup an existing object provided by
[`ReplaceBuilder::header()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/#method-header) or [`ReplaceBuilder::header_values()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.ReplaceBuilder/#method-header_values) should match the request
headers used to write the replacement object provided by [`Replace::header()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Replace/#method-header) or
[`Replace::header_values()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Replace/#method-header_values).  Additionally if you use a lookup or insert to create an object
then later replace it the [`Replace::vary_by()`](https://www.fastly.com/documentation/reference/compute/sdks/rust/fastly/cache/core/struct.Replace/#method-vary_by) should match.  If the header or vary values
are different between the existing object and the replacement object other requests looking up
the object may not be able to find the replacement object.

**Parameters**

- `key`: `crate::CacheKey`

**Returns**

`ReplaceBuilder`