.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _edg_sparql_endpoint:

Accessing the SPARQL endpoint
=============================

In the following sections we look specifically at how to access the SPARQL endpoint with calls from external systems. First we look at accessing the endpoint via TQ's Swagger API and cURL . Next, how to access via the SPARQL client. And finally how to call the endpoint with some sample Python code (this will require a basic understanding of `Python`_). 

To learn about `SPARQL`_ in TQ Data Foundation, please consult the `SPARQL documentation <../../../reference/SPARQLQueryPanel.html>`_. 

.. contents::
.. _1-accessing_SPARQL_via_Swagger_and_cURL:

1. Accessing SPARQL via Swagger and cURL
----------------------------------------

In this section you will learn to navigate to Swaggers SPARQL endpoint, and execute a simple SPARQL query. We will be querying over Data Foundation's `sample data <https://archive.topquadrant.com/topbraid-composer-install/>`_. 

To learn more about accessing and using Swagger in Data Foundation, please consult the following documentation: `Web services and Swagger <../../../scripting/services.html>`_ and `Swagger References <../../../reference/APIs_WebServicesSwaggerUI.html>`_. 

The first step is to click on the Asset Operations icon in the header of your target asset collection, i.e. the asset collection which you wish to run your SPARQL query. Select the Kennedy Family data graph, click the Asset Operations icon, select "Web Services Swagger UI", and navigate to "SPARQL".  

.. figure:: _images/swagger_sparql_endpoint.png
   :alt: Swagger SPARQL Endpoint
   :align: center
   :class: edg-figure

   **The SPARQL Swagger endpoint for the Kennedy Family asset collection**

Under SPARQL you will see two options, either access SPARQL endpoint using GET or POST requests. Let us test POST. Click on it and selecting "Try it out"

.. figure:: _images/swagger_sparql_endpoint_query.png
   :alt: Swagger SPARQL Endpoint Query
   :align: center
   :class: edg-figure

   **The SPARQL endpoint in Swagger for the Kennedy Family asset collection**

The default-graph-uri will already have the asset collections URI as a value, but it is possible to query over other asset collections by editing this field. As you have selected the Kennedy Family data graph, this value should read "urn:x-evn-master:kennedy_family". There are several other options available here, for example, you can specify the format of the response (formats are dependant on the type of query), whether to include imported graphs, etc. These can be viewed in Swagger as optional fields. We are only interested here in the query field.

Enter the following SPARQL query into the query field:

.. code-block:: text 

   PREFIX schema: <http://schema.org/>
   SELECT * 
   {
      ?s a schema:Person;
      schema:birthDate ?birthDate;
      schema:deathDate ?deathDate;
      schema:gender ?gender.
   }

The response body is a downloadable file, so you can click the "Download file" option to download the result of this query. 

The same query can be executed using the following cURL command (this has been adapted slightly from what Swagger provides): 

.. code-block:: bash 

   curl -X POST \
  'http://localhost:8083/tbl/sparql' \
  -H 'accept: */*' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'default-graph-uri=urn:x-evn-master:kennedy_family' \
  --data-urlencode 'format=' \
  --data-urlencode 'labeled=' \
  --data-urlencode 'processId=' \
  --data-urlencode 'query=PREFIX schema: <http://schema.org/> SELECT * { ?s a schema:Person; schema:birthDate ?birthDate; schema:deathDate ?deathDate; schema:gender ?gender.}' \
  --data-urlencode 'with-imports='

The SPARQL endpoint has a URL of ``http://localhost:8083/tbl/sparql``. This example assumes you are running on localhost with no authentication. When running Data Foundation on SaaS you would replace "localhost:8083" with the URL of your server. For more on the differents methods for authenticating, please see the documentation on `authentication <../../../administrator_guide/edg_installation_and_authentication/authentication_edg_background.html>`_, or consult the previous section on authentication for accessing the GraphQL endpoint `GraphQL endpoint authentication <../edg_graphql_endpoint/index.html#using-authentication-in-edg>`_


.. _2-accessing_SPARQL_endpoint_client:

2. Accessing SPARQL endpoint client
-----------------------------------

You can also access a SPARQL client by putting ``http://localhost:8083/tbl/sparql`` into your browser. This gives you access to the SPARQL endpoint client. Here you can select a default graph from the drop down menu, and run queries against that graph. You can also see the URIs for each of the different graphs which are available to query against, including the change graphs. 

.. figure:: _images/edg_sparql_endpoint_client.png
   :alt: SPARQL Endpoint Client
   :align: center
   :class: edg-figure

   **The SPARQL endpoint client querying the Kennedy Family asset collection**
   


.. _3-accessing_SPARQL_using_python_script:

3. Accessing SPARQL using a Python Script
-----------------------------------------

In this section we take the above SPARQL endpoint and write a piece of Python script to allow you to make a call to Data Foundation, which takes as parameters the URL of your server, the asset collection, and the query. The python code will need to import two libraries, requests (to handle the HTTP requests) and sys (to handle input parameters). Next we write a main function, which first checks we have provided the correct number of parameters, and if yes, takes these parameters, stores them as variables, and passes them to the function "sparql_query". 

.. literalinclude:: _code/sparql_query.py
   :language: python
   :lines: 1-12

Next we write the sparql_query function. This function takes the input url, the name of the asset collection, and finally the SPARQL query and uses these to generate a HTTP post request. If successful, it returns the response and prints to console, and if not it generates an error message. 

.. literalinclude:: _code/sparql_query.py
   :language: python
   :lines: 15 - 40


You can download the complete code example here :download:`sparql_query.py <_code/sparql_query.py>`

To test this, running EDG Studio locally, use the following command - 

.. code-block:: bash 

   python sparql_query.py --input_url "http://localhost:8083" --default_graph_uri "urn:x-evn-master:kennedy_family" --query "PREFIX schema: <http://schema.org/> SELECT * { ?s a schema:Person; schema:birthDate ?birthDate; schema:deathDate ?deathDate; schema:gender ?gender.}"