<?xml version='1.0' encoding="ISO-8859-1"?>

<part id="tracker-overview">
  <title>Overview</title>
  <partintro>
    <para>
      Tracker SPARQL allows creating and connecting to one or more triplestore databases.
      It is used by the
      <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/tracker-miners/">
        Tracker Miners filesystem indexer
      </ulink>, and can also store and publish any kind of app data.
    </para>
    <para>
      Querying data is done using the SPARQL graph query language. See the
      <link linkend="Examples">Examples</link> to find out how this works.
      Storing data can also be done using SPARQL, or using the
      <type><link linkend="TrackerResource">TrackerResource</link></type> API.
    </para>
    <para>
      You can share a database over D-Bus using the
      <type><link linkend="TrackerEndpoint">TrackerEndpoint</link></type> API,
      allowing other libtracker-sparql users to query from it, either
      by referencing it in a <userinput>SELECT { SERVICE ... }</userinput>
      query, or by connecting directly with
      <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
    </para>
    <para>
      Tracker SPARQL partitions the database into multiple graphs.
      You can implementing access control restrictions based on
      graphs, and we provide a Flatpak portal that does so.
      The number of graphs is <link linkend="limits">limited</link>.
    </para>
  </partintro>

  <chapter id="tracker-overview-connection-methods">
    <title>Connection methods</title>

    <para>
        You can create and access a private store using
        <function><link linkend="tracker-sparql-connection-new">tracker_sparql_connection_new</link></function>.
        This is useful to store app-specific data.
    </para>
    <para>
        To connect to another database on the same local machine, such as the
        one exposed by Tracker Miner FS, use
        <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
    </para>
    <para>
        To connect to another a database on a remote machine, use
        <function><link linkend="tracker-sparql-connection-remote-new">tracker_sparql_connection_remote_new</link></function>.
        This can be used to query online databases that provide a SPARQL
        endpoint, such as
        <ulink role="online-location" url="https://wiki.dbpedia.org/about">DBpedia</ulink>
        .
    </para>
  </chapter>

  <chapter id="tracker-overview-flatpak">
    <title>Connecting from Flatpak</title>

    <para>
        Tracker SPARQL provides a portal for the
        <ulink role="online-location" url="https://flatpak.org/">Flatpak</ulink>
        application sandboxing system. This lets
        you control which parts of a database each app can query.
    </para>
    <para>
        The app's Flatpak manifest needs to specify which graph(s) the app will
        access. See the <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/tracker/-/blob/master/examples/flatpak/org.example.TrackerSandbox.json">example app</ulink>
        and the <ulink role="online-location" url="https://gnome.pages.gitlab.gnome.org/tracker/docs/commandline/#tracker-xdg-portal-3">portal documentation</ulink>
        to see how.
        No code changes are needed in the app, as
        <function><link linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
        will automatically try connect via the portal
        if it can't talk to the given D-Bus name directly.
    </para>
    <para>
        Tracker SPARQL is included in the <ulink role="online-location" url="https://docs.flatpak.org/en/latest/available-runtimes.html#gnome">GNOME Flatpak SDK and runtime</ulink>.
        If the app uses a different runtime, you may need to build Tracker SPARQL in the app manifest.
    </para>
    <para>
        The app might use the Tracker Miner FS search index. Ideally this is done via the portal,
        using the search index maintained on the host. Since not all OSes ship tracker-miner-fs-3,
        we recommend that apps bundle it inside the Flatpak and connect to the bundled version as
        a fallback. See <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/gnome-music/">GNOME Music</ulink>
        for an example of how to do this.
    </para>
  </chapter>
</part>
