diff options
Diffstat (limited to 'docs/reference/libtracker-sparql/overview.xml')
| -rw-r--r-- | docs/reference/libtracker-sparql/overview.xml | 60 |
1 files changed, 53 insertions, 7 deletions
diff --git a/docs/reference/libtracker-sparql/overview.xml b/docs/reference/libtracker-sparql/overview.xml index 0e746e1a1..49587360f 100644 --- a/docs/reference/libtracker-sparql/overview.xml +++ b/docs/reference/libtracker-sparql/overview.xml @@ -4,13 +4,17 @@ <title>Overview</title> <partintro> <para> - The libtracker-sparql library allows creating and connecting to - one or more "triplestore" databases. + 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> - Data queries and updates are done using the SPARQL graph query - language. The <type><link linkend="TrackerResource">TrackerResource</link></type> - API provides helpers for updating data. + 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 @@ -20,24 +24,66 @@ 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 the Tracker filesystem miner, use + 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> |