--- title: TransactionInsertBuilder summary: A builder-style API for configuring a transactional cache insertion. url: https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.TransactionInsertBuilder/ --- **Kind:** Class **Module:** [core](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/) **Package:** compute-sdk-cpp 0.7.0 **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L256 Include `fastly/cache/core.h` to use this class. A builder-style API for configuring a transactional cache insertion. This builder is used to insert a new item into the cache during a transaction. All builder methods consume the builder and return it for method chaining. ## Methods ### deliver_node_max_age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L325 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::deliver_node_max_age(std::chrono::nanoseconds duration) && ``` Sets the maximum time the cached item may live on a deliver node in a POP. **Parameters** - `duration`: `std::chrono::nanoseconds` **Returns** `TransactionInsertBuilder` ### execute **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L348 ```cpp tl::expected fastly::cache::core::TransactionInsertBuilder::execute() && ``` Begin the insertion, returning a `StreamingBody` for providing the cached object itself. For the insertion to complete successfully, the object must be written into the `StreamingBody`, and then `StreamingBody::finish` must be called. If the `StreamingBody` is dropped before calling `StreamingBody::finish`, the insertion is considered incomplete, and any concurrent lookups that may be reading from the object as it is streamed into the cache may encounter a streaming error. **Returns** `tl::expected` ### execute_and_stream_back **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L366 ```cpp tl::expected, CacheError> fastly::cache::core::TransactionInsertBuilder::execute_and_stream_back() && ``` Begin the insertion, and provide a [`Found`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/) object that can be used to stream out of the newly-inserted object. For the insertion to complete successfully, the object must be written into the `StreamingBody`, and then `StreamingBody::finish` must be called. If the `StreamingBody` is dropped before calling `StreamingBody::finish`, the insertion is considered incomplete, and any concurrent lookups that may be reading from the object as it is streamed into the cache may encounter a streaming error. The returned [`Found`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/) object allows the client inserting a cache item to efficiently read back the contents of that item, avoiding the need to buffer contents for copying to multiple destinations. This pattern is commonly required when caching an item that also must be provided to, e.g., the client response. **Returns** `tl::expected, CacheError>` ### initial_age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L268 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::initial_age(std::chrono::nanoseconds age) && ``` Sets the initial age of the cached item, to be used in freshness calculations. The initial age is 0 by default. **Parameters** - `age`: `std::chrono::nanoseconds` **Returns** `TransactionInsertBuilder` ### known_length **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L309 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::known_length(std::uint64_t length) && ``` Sets the size of the cached item, in bytes, when known prior to actually providing the bytes. It is preferable to provide a length, if possible. Clients that begin streaming the item’s contents before it is completely provided will see the promised length which allows them to, for example, use `content-length` instead of `transfer-encoding: chunked` if the item is used as the body of a `Request` or `Response`. **Parameters** - `length`: `std::uint64_t` **Returns** `TransactionInsertBuilder` ### on_behalf_of **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L337 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::on_behalf_of(std::string service) && ``` Perform this insert on behalf of another service, using its data store. *Internal / Privileged* This operation is privileged, and attempts to use this functionality without proper privileges will cause errors. If you are interested in having two or more of your services share the same cache, please talk to your Fastly account representative. While we have no plans to offer this ability widely – this capability is only currently allowed for Fastly-internal services – we may revisit this decision given sufficient customer input. **Parameters** - `service`: `std::string` **Returns** `TransactionInsertBuilder` ### sensitive_data **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L321 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::sensitive_data(bool is_sensitive) && ``` Enable or disable PCI/HIPAA-compliant non-volatile caching. By default, this is false. See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery) for details. **Parameters** - `is_sensitive`: `bool` **Returns** `TransactionInsertBuilder` ### stale_while_revalidate **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L282 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::stale_while_revalidate(std::chrono::nanoseconds duration) && ``` Sets the stale-while-revalidate period for the cached item, which is the time for which the item can be safely used despite being considered stale. Having a stale-while-revalidate period provides a signal that the cache should be updated (or its contents otherwise revalidated for freshness) asynchronously, while the stale cached item continues to be used, rather than blocking on updating the cached item. The methods [`Found::is_usable`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/#method-is_usable) and [`Found::is_stale`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Found/#method-is_stale) can be used to determine the current state of a found item. The stale-while-revalidate period is 0 by default. **Parameters** - `duration`: `std::chrono::nanoseconds` **Returns** `TransactionInsertBuilder` ### surrogate_keys **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L299 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::surrogate_keys(std::vector keys) && ``` Sets the surrogate keys that can be used for purging this cached item. Surrogate key purges are the only means to purge specific items from the cache. At least one surrogate key must be set in order to remove an item without performing a [purge-all](https://www.fastly.com/documentation/guides/concepts/cache/purging/#purge-all), waiting for the item’s TTL to elapse, or overwriting the item with `crate::cache::core::insert()`. Surrogate keys must contain only printable ASCII characters (those between 0x21 and 0x7E, inclusive). Any invalid keys will be ignored. See the [Fastly surrogate keys guide](https://www.fastly.com/documentation/guides/full-site-delivery/purging/working-with-surrogate-keys/) for details. **Parameters** - `keys`: `std::vector` **Returns** `TransactionInsertBuilder` ### user_metadata **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L312 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::user_metadata(std::vector metadata) && ``` Sets the user-defined metadata to associate with the cached item. **Parameters** - `metadata`: `std::vector` **Returns** `TransactionInsertBuilder` ### vary_by **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L264 ```cpp TransactionInsertBuilder fastly::cache::core::TransactionInsertBuilder::vary_by(std::vector headers) && ``` Sets the list of headers that must match when looking up this cached item. The header values must be provided by calling [`TransactionLookupBuilder::header()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.TransactionLookupBuilder/#method-header) or [`TransactionLookupBuilder::header_values()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.TransactionLookupBuilder/#method-header_values). The header values may be a subset or superset of the header names supplied here. **Parameters** - `headers`: `std::vector` **Returns** `TransactionInsertBuilder`