--- title: InsertBuilder summary: A builder-style API for configuring a non-transactional cache insertion. url: https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.InsertBuilder/ --- **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#L897 Include `fastly/cache/core.h` to use this class. A builder-style API for configuring a non-transactional cache insertion. Like [`lookup()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/fn.lookup/), `insert()` may race with concurrent lookups or insertions, and will unconditionally overwrite existing cached items rather than allowing for revalidation of an existing object. The transactional equivalent is [`Transaction::insert()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Transaction/#method-insert), which may only be called following a transactional lookup when [`Transaction::must_insert_or_update()`](https://www.fastly.com/documentation/reference/compute/sdks/cpp/fastly/cache/core/class.Transaction/#method-must_insert_or_update) returns `true`. ## Methods ### deliver_node_max_age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L998 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::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** `InsertBuilder` ### execute **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L1014 ```cpp tl::expected fastly::cache::core::InsertBuilder::execute() && ``` Begin the insertion, returning a `StreamingBody` for providing the cached object itself. **Returns** `tl::expected` ### header **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L949 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::header(std::string_view name, const http::HeaderValue &value) && ``` Sets a single-value header for this lookup, discarding any previous values associated with the header `name`. Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the [HTTP Vary](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.5) header, but the APIs in this module are not suitable for HTTP caching out-of-the-box. Future SDK releases will contain an HTTP Cache API. The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via e.g. `crate::cache::core::InsertBuilder::vary_by`. A lookup will succeed when there is at least one cached item that matches lookup’s cache key, and all of the lookup’s headers included in the cache items’ vary_by list match the corresponding headers in that cached item. A typical example is a cached HTTP response, where the request had an Accept-Encoding header. In that case, the origin server may or may not decide on a given encoding, and whether that same response is suitable for a request with a different (or missing) Accept-Encoding header is determined by whether Accept-Encoding is listed in Vary header in the origin’s response. **Parameters** - `name`: `std::string_view` - `value`: `const http::HeaderValue &` **Returns** `InsertBuilder` ### header_values **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L921 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::header_values(std::string_view name, std::span values) && ``` Sets a multi-value header for this lookup, discarding any previous values associated with the header name. Note: These headers are narrowly useful for implementing cache lookups incorporating the semantics of the [HTTP Vary](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.5) header, but the APIs in this module are not suitable for HTTP caching out-of-the-box. Future SDK releases will contain an HTTP Cache API. The headers act as additional factors in object selection, and the choice of which headers to factor in is determined during insertion, via e.g. `crate::cache::core::InsertBuilder::vary_by`. A lookup will succeed when there is at least one cached item that matches lookup’s cache key, and all of the lookup’s headers included in the cache items’ vary_by list match the corresponding headers in that cached item. A typical example is a cached HTTP response, where the request had an Accept-Encoding header. In that case, the origin server may or may not decide on a given encoding, and whether that same response is suitable for a request with a different (or missing) Accept-Encoding header is determined by whether Accept-Encoding is listed in Vary header in the origin’s response. **Parameters** - `name`: `std::string_view` - `values`: `std::span` **Returns** `InsertBuilder` ### initial_age **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L959 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::initial_age(std::chrono::nanoseconds age) && ``` Sets the initial age of the cached item, to be used in freshness calculations. The initial age is zero by default. **Parameters** - `age`: `std::chrono::nanoseconds` **Returns** `InsertBuilder` ### known_length **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L983 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::known_length(std::uint64_t length) && ``` Sets the known length of the cached item. **Parameters** - `length`: `std::uint64_t` **Returns** `InsertBuilder` ### on_behalf_of **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L1010 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::on_behalf_of(std::string service) && ``` Perform this insertion 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** `InsertBuilder` ### sensitive_data **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L995 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::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** `InsertBuilder` ### stale_while_revalidate **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L963 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::stale_while_revalidate(std::chrono::nanoseconds duration) && ``` Sets the time for which a cached item can safely be used despite being considered stale. **Parameters** - `duration`: `std::chrono::nanoseconds` **Returns** `InsertBuilder` ### surrogate_keys **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L980 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::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** `InsertBuilder` ### user_metadata **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L986 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::user_metadata(std::vector metadata) && ``` Sets the user-defined metadata to associate with the cached item. **Parameters** - `metadata`: `std::vector` **Returns** `InsertBuilder` ### vary_by **Source:** https://github.com/fastly/compute-sdk-cpp/blob/ff911e47be2f319e83a9cde960d2c3c5db534280/include/fastly/cache/core.h#L953 ```cpp InsertBuilder fastly::cache::core::InsertBuilder::vary_by(std::vector headers) && ``` Sets the list of headers that must match when looking up this cached item. **Parameters** - `headers`: `std::vector` **Returns** `InsertBuilder`