--- title: Work with saved queries url: https://docs.triply.cc/how-to/saved-queries/ description: Save a SPARQL query in TriplyDB, version it, share it by URL and call it as an API. --- # Work with saved queries A Saved Query is a versioned SPARQL query with its own URL. Using this URL, users are able to view any version of the query and its results. It can also be used to run the query and retrieve the results from a browser or a program, removing the hassle of figuring out how to run a SPARQL query. A saved query is the query object; each save adds a version; the URL addresses either, frozen with a version number and following the latest without one. See [Saved query](https://docs.triply.cc/concepts/what-triplydb-is/#saved-query) for how the three relate. ## How to save a query You need to be logged in and have authorization rights on the dataset; without them the save button does not appear. 1. Write the query in the [SPARQL IDE](https://docs.triply.cc/how-to/query-data/#run-a-sparql-query) and pick a visualization. 2. Click the save button: ![The save query button highlighted](https://docs.triply.cc/assets/save-query-highlighted.png) The visualisation is saved along with the query — Table, Response, Chart, Geo and the rest — so pick the one you want people to see when they open the link. ## Creating a new version Updating the saved query can be done by clicking a query in the Saved Queries tab and editing the query or the visualization. Hit the save button to save it as a new version. Older versions stay reachable at their own URLs. ## Deleting a saved query If you want to delete a saved query, you can do so by clicking the three dots on the top right corner of the query, as shown in the image below, and then clicking `Delete`. ![Deleting a saved query](https://docs.triply.cc/assets/delete-query.png) Deleting removes the query and all of its versions. ## Sharing a saved query To share a saved query, for example in [data stories](https://docs.triply.cc/how-to/data-stories/), you can copy the link that is used when you open the query in TriplyDB. For version 9 of the query `timeline-cars` under the account `DBpedia-association`, that link is: ```uri https://triplydb.com/DBpedia-association/-/queries/timeline-cars/9 ``` To follow the **latest** version instead, omit the version number: ```uri https://triplydb.com/DBpedia-association/-/queries/timeline-cars ``` Pin a version for anything that has to keep working — an application, a citation, a published data story — and omit it when readers should see current work. Sharing a link does not grant access to the underlying dataset. If a colleague opens the link and sees nothing, check the query's [access level](https://docs.triply.cc/concepts/access-levels/). The SPARQL IDE also has a share icon, in its top-right corner, which offers the query as a URL-encoded link, as a short URL redirecting to it, and as a cURL command for testing from a terminal. URL-encoded queries get long, and some applications cut URLs off at a maximum length — often 1,024 characters. Saved queries have none of those limits, which is why they are the better option for anything you intend to keep. ## Transferring and copying a query Both move the query between an account and a group, in either direction, and neither moves the dataset it queries. To **transfer** a query, go to the settings field on the query page, ![Transfer a SPARQL query](https://docs.triply.cc/assets/where-find-transfer.png) choose transfer: ![Transfer a SPARQL query](https://docs.triply.cc/assets/transfer-query.png) and then choose where the SPARQL query should be moved to: ![Transfer a SPARQL query](https://docs.triply.cc/assets/transfer-to-organization.png) After the destination is set you are redirected to the query's new page. To **copy** a query instead of moving it, click the three dots in the upper right corner of the query and choose the copy option: ![Copy query](https://docs.triply.cc/assets/copyQuery.png) Then choose the destination: ![Select group](https://docs.triply.cc/assets/selectOrganization.png) ## Downloading a query result The result of a query can be downloaded via the TriplyDB interface. After saving the query, open it in TriplyDB. e.g. . You can download results in different data format, depending on which visualization option you use. For example, if you want to download the results in a `.json` format, you can choose the option `Response` and click on the download icon or scroll down and click on `Download result`. ![Download the query result via the download icon.](https://docs.triply.cc/assets/queryResult.png) ![Download the query result via the button `Download result`.](https://docs.triply.cc/assets/queryResult2.png) The downloaded file is automatically stored in the `Downloads`-folder and has the name of the query. In our example, the file is called `timeline-cars.json`. Not every visualisation can be downloaded — Gallery, Geo, Geo-3D, Geo events and Timeline have no download at all. See [Result formats](https://docs.triply.cc/reference/saved-queries/#result-formats) for which visualisation produces which file. ## Using a saved query as a RESTful API Each TriplyDB instance has a fully RESTful API. The TriplyDB RESTful API is extended for saved SPARQL queries. A saved query can be used as a RESTful API to retrieve data from your linked dataset. The URL next to the keyword `API` is the RESTful API URL and can be used with RESTful API libraries. You can copy the RESTful API by pressing the copy button just behind the URL. Pressing the copy button from the above query will result in the following run url: ```uri https://api.triplydb.com/queries/DBpedia-association/timeline-cars/run ``` When you copy this URL in your browser or fetch the URL with curl, you will get a get request to a RESTful API and get a JSON representation of the data in your browser or command window. A saved query can also declare **API variables**: named parameters substituted into the query string when it runs. That is what lets one saved query answer many questions — an application passes different inputs instead of building SPARQL strings, or keeping a separate saved query per case. Variables are passed as arguments to the endpoint, or as the first argument to `results()` in TriplyDB.js. A single result set stops at 10,000 results. See [Paginate SPARQL results](https://docs.triply.cc/how-to/sparql-pagination/) for retrieving more than that. ## Using a saved query in Python or R notebooks SPARQL queries as a RESTful API, also means you can transport your data to your Python script, R script or Jupyter notebook. To use the result set from your SPARQL query you need to connect your script to the saved SPARQL query. To do this you will need to write a small connector. To help you out TriplyDB has added a code snippet generator for Python and R. This snippet contains the code to retrieve the data from the SPARQL query into your script or notebook. You can open the code snippet generator by clicking on the '</>' button on the right side of the screen. Clicking the '</>' button opens the code snippet screen. Here you select the snippet in the language you want to have, either Python or R. You can then copy the snippet, by clicking the 'copy to clipboard' button or selecting the snippet and pressing `ctrl-c`. Now you can paste the code in the location you want to use the data. The data is stored in the `data` variable in `JSON` format. When the SPARQL query is not public, but instead either private or internal, you will need to add an authorization header to the get request. Without the authorization header the request will return an incorrect response rather than an obvious refusal. See [Create an API token](https://docs.triply.cc/how-to/create-an-api-token/) for the token that header carries. ## Query metadata Every Saved Query has a metadata section, holding a title and description you write, the access level and version, and links to the dataset and the service the query runs against. Further metadata can be written into the query string itself as GRLC annotations. See [Saved queries](https://docs.triply.cc/reference/saved-queries/#metadata-fields) for the fields and the annotation format. ## Related - [Saved queries](https://docs.triply.cc/reference/saved-queries/) — URLs, limits, result formats and metadata - [Paginate SPARQL results](https://docs.triply.cc/how-to/sparql-pagination/) — getting past the 10,000 limit - [Build a data story](https://docs.triply.cc/how-to/data-stories/) — presenting a query's results with explanation - [SPARQL: the basics](https://docs.triply.cc/concepts/sparql-basics/) — writing the query in the first place