Enable query response caching to optimize services

An organization in New Zealand wants to make its Hochstetter's frog habitat data publicly accessible to increase awareness and support conservation efforts. By sharing this information openly, the organization expects a growing number of users to view maps and submit queries through web maps, apps, dashboards, and other client applications.

While increased access is a positive outcome, the organization is concerned that a high volume of repeated queries could place additional strain on its ArcGIS Enterprise system. Rather than scaling infrastructure by adding more CPU and RAM, the organization looks for a more efficient way to handle this anticipated load. Because many users are expected to request the same data repeatedly, the Enterprise administrator decides to use query response caching to improve performance and reduce database load. Query response caching is a technique used in computing and data systems where the results of a query (a request for data or information) are stored temporarily in a cache. When the same query is requested again, instead of processing the query from scratch, the system retrieves the stored result from the cache and returns it immediately. Benefits of query response caching include improved performance and speed, reduced load on backend systems, scalability, and more.

You'll use a sample hosted feature layer representing the Hochstetter's frog habitat to enable response caching in Enterprise. You'll learn how response caching works, when it is appropriate to use, and how to configure it for hosted feature layers. Once you complete this tutorial, you'll have the skills to configure response caching for your own hosted feature layers, which improves performance for users accessing biodiversity maps, conservation dashboards, and other applications that rely on consistent query patterns.

This tutorial was last tested on January 21, 2026, using ArcGIS Pro 3.6 and ArcGIS Enterprise 12.0. If you're using a different version of ArcGIS Pro or ArcGIS Enterprise, you may encounter different functionality and results.

Requirements

• Publisher or Administrator role in an ArcGIS Enterprise (learn more)
• ArcGIS Enterprise version 11.0 or later using a valid certificate and configured with an object store
• ArcGIS Pro

Publish and explore a hosted feature layer

You'll start by publishing the Hochstetter's frog habitat dataset as a hosted feature layer directly in your Enterprise portal. You'll review its properties to understand how it responds to client queries. You'll examine the layer's item details and settings in the portal, access the feature layer's REST endpoint, and browse to the admin service endpoint to identify service-level properties related to query behavior and caching. Understanding these properties is essential before enabling response caching, since not all hosted feature layers or workflows are suitable candidates for caching.

Publish a hosted feature layer

To enable response caching, you'll create a hosted feature layer from a GeoJSON file.

1. Download the frog habitat data.

   The sample data is a GeoJSON file.

2. Sign in to your ArcGIS organizational account.

   Note:

   If you don't have an organizational account, see options for software access.

3. On the ribbon, click the Content tab.

   

4. Click New item.

   

5. In the New item window, click Feature layer.

   

6. On the Create a feature layer page, scroll to the bottom and click Upload a file.

   

7. Click Next.
8. Click Your device. Browse to the Downloads folder, select FrogHabitat.geojson, and click Open.

   The default location for downloads is the Downloads folder, though you may have specified a different location to save the file.

9. On the New item page, add the following information:
   • For Title, keep the current title of FrogHabitat.
   • For Tags, type biodiversity, frogs, and habitat, pressing the Tab key after each entry.
   • For Summary, type or copy and paste: This hosted feature layer stores the protected habitat river lines for the endangered frog species in New Zealand.

   

10. Click Save.

    The item details page for the hosted feature layer appears.

    

    Next, you'll set the sharing properties so everyone can access the feature layer.

11. Click Share.

    

12. In the Share window, click Everyone (public).

    

    A public sharing level is appropriate for this use case in which conservation data is intended to be accessible to an external audience.

13. Click Save.

Explore the properties

Next, you'll explore the properties of the newly published hosted feature service in Enterprise and learn which settings control how the layer responds to client requests.

1. On the FrogHabitat feature layer's details page, for URL, click the View button.

   

   The ArcGIS REST Services Directory page appears; this is an HTML view of the REST endpoint for the service.

   

2. Under Layers, click lines.

   

   The HTML view of the REST endpoint for this individual layer appears.

   

   This granular level allows you to control which layers will write response cache content to the object store. Next, you'll explore configuration information for the layer.

3. Under the path at the top of the page, click the JSON link.

   

   This page shows all the configuration information for the layer. You'll search for a specific command using Windows search functionality.

4. On the keyboard, press Ctrl and the F key to open a search box.

   

5. In the search box, type editingInfo.

   

   The text you typed is automatically highlighted on the page.

   The layer has a timestamp for the last edit. Having a record of the last edit date is important to ensure that a client isn't using an outdated cached response that doesn't reflect the most recent edits. Because cached responses are invalidated by edits to the layer, caching is most effective for layers that are edited infrequently.

6. Search for the supportsQueryWithCacheHint property.

   

   This property has a value of false, which means query response caching is not enabled for this layer.

You published a hosted feature layer directly in the Enterprise portal using a GeoJSON file. You accessed the REST endpoint of the feature service to confirm it tracks the last edit date of the data but doesn't have response caching enabled. Next, you'll turn on this capability.

Enable query response caching for the layer

Next, you'll enable response caching for the FrogHabitat hosted feature layer by changing the supportsQueryWithCacheHint property to true. This enables Enterprise to cache the responses from queries in the object store after retrieving the response from the relational store once. Because providing the cached response from the object store is more efficient than running a query against the relational store, response caching optimizes the efficiency of the hosted feature layer.

Because these efficiency gains only happen when a particular query is repeated, response caching is best suited for cases in which users are making the same queries many times.

Enable response caching

You'll enable response caching by changing the supportsQueryWithCacheHint property to true. The updateDefinition operation allows you to update a definition property in a feature service layer.

1. In your browser, ensure the tab with the HTML view for the lines layer is active.

   

   To use the updateDefinition operation, you must access the layer admin resource. You can do this by adding admin to the URL.

2. In the address bar of the browser tab, replace rest/services with rest/admin/services.

   

3. Press Enter.

   

   The admin page appears.

4. At the bottom of the page, click Update Definition.

   

5. For Input, copy and paste the following JSON snippet:
   {
                    "layerCache": {
                        "enabled": true,
                        "expiration": 1
                    }
   }

   

   Note:

   Match the indentation shown in the image.

   This sets the layer cache to true and adds an expiration date to define the number of days a cache will be stored before it is removed. The expiration property value is in days, so any cached responses for this layer will be invalidated in one day. Higher values mean that a cached response remains available for longer. Higher values also mean there will be a larger number of cached responses, which will require more disk space.

6. Click updateDefinition.

   

   A JSON response confirms the operation was successful.

   

7. Activate the browser tab with the JSON view of the layer properties and refresh the page.
8. Search for the supportsQueryWithCacheHint property.

   

Make requests to use response caching

If response caching is enabled for a layer, clients that are aware of how response caching works will generally structure queries to use it. These clients include ArcGIS Pro, Map Viewer, and apps built with the ArcGIS Maps SDK for JavaScript. But queries won't always be structured that way, especially if they are made by other clients. Refer to Response caching for hosted feature service layers in ArcGIS Enterprise for documentation on how to structure requests for response caching.

You'll use a notebook created in ArcGIS Notebooks to simulate requests to the service from users so you can see how requests need to be structured for response caching.

1. Return to the browser tab with Update Definition shown.

   

2. In the URL, replace rest/admin/services with rest/services (removing the admin), remove updateDefinition at the end, and press Enter.

   

   You are returned to the ArcGIS REST Services Directory page.

   

3. Scroll to the bottom of the page and click Query.

   

   When any client makes a query request on this service, it uses this query endpoint. You'll use this endpoint in the notebook to make automated requests.

4. Copy the URL for this query page.
5. Start ArcGIS Pro. If prompted, sign in using your licensed ArcGIS organizational account.

   Note:

   If you don't have access to ArcGIS Pro or an ArcGIS organizational account, see options for software access.

   When you open ArcGIS Pro, you're given the option to create a new project or open an existing one. If you've created a project before, you'll see a list of recent projects.

6. Under New Project, click Start without a template.

   

7. Download the printResponseInfo notebook.
8. On the ribbon, on the Insert tab, click the drop-down arrow next to New Notebook and choose Add and Open Notebook.

   

9. Browse to the folder where you saved printResponseInfo.ipynb, choose printResponseInfo.ipynb, and click OK.

   The notebook appears. You'll select the first code cell and run it.

   

10. In the notebook, select the first code cell and click the Run button.

    

    Note:

    You can also press Ctrl+Enter to run the selected code block.

11. In the second code cell, replace the queryURL value on line 1 with the query URL you copied for your service.

    

    Ensure that the URL is enclosed in quotation marks.

12. Run the second code cell.

    

    The response includes the following values:

    • Status code—Indicates whether the request was successful, which is a value of 200
    • Date—The date and time the request was made

    Note:

    If the Status code value is not 200, make sure you provided the correct queryURL value.

    Next, you'll run the second cell a few times to see how the response changes.

13. Run the second cell multiple times.

    For Date, the date remains the same and the time changes; however, the response information is otherwise identical. The data for this query is being retrieved from the relational store each time the query is made.

14. Change line 2 to resultType = "tile" and run the cell once.

    

    The response information is like the previous requests. The data for this request was also retrieved from the relational store. But unlike the previous queries, the response was cached in the object store because the request used resultType = "tile".

15. Run the cell again.

    

    This time the response includes an additional header, x-esri-ftiles-cache-compress: true. This indicates the response came from the value that was cached in the object store from the previous request. There was no need to run a new query on the relational store.

    If you do not see the x-esri-ftiles-cache-compress header, confirm you have enabled query response caching on the layer and that line 2 is set to resultType = "tile".

16. Change line 3 to cacheHint = "true" and run the cell once.

    

    This response is like the one you saw in the original query. Because it is a different query from the last request, it does not match any previously cached response, so the response required a new query on the relational store. Because the request used cacheHint = "true", the response for this request was also cached in the object store.

    Note:

    It is not required that you also use resultType = "tile" with cacheHint = "true". One or the other alone is enough to ensure the request uses response caching.

17. Run the cell again.

    This time the response includes a new x-esri-cache-hint-features: true header. This indicates the response came from the cached value in the object store.

    

    Next, you'll change the number of features value to see how the response is affected.

18. In line 4, change the numFeatures value to 5 and run the cell.

    

    Because the query is once again different, there is no corresponding cached response already available. The data came from a query on the relational store, as evidenced by the lack of x-esri-ftiles-cache-compress: true or x-esri-cache-hint-features: true headers.

19. Run the cell again.

    

    Now the response includes a x-esri-cache-hint-features: true header, showing that the service used the value that was cached in the object store from the previous request.

    The resultType = "tile" or cacheHint = "true" parameters are required to use response caching. When a user makes a request with either parameter on a layer with response caching enabled, the data for the response will come from the object store if it has already been cached. If it hasn't already been cached, a new query will run on the relational store, and the response will be cached in the object store. Until the cache expires, if any user makes the same request later, the data will come from the object store instead of needing to make a new query on the relational store.

By enabling query response caching, the organization has taken an important step toward making Hochstetter's frog habitat data widely accessible without placing unnecessary strain on its ArcGIS Enterprise infrastructure. As public interest in conservation grows and more users explore maps, apps, and dashboards built from this data, repeated queries can now be served efficiently from the object store rather than the relational store. This allows the organization to increase visibility while optimizing the resource usage of this hosted feature layer.

You can find more tutorials in the tutorial gallery.

Acknowledgements

• Frog habitat data provided by Land Information New Zealand and the New Zealand Government, All rights reserved. Bay of Plenty Regional Council.