From c32f172f1b48f6cfe9845ca233f643bde81abd0c Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Tue, 13 Oct 2020 13:51:09 +0200 Subject: docs: Add information related to Flatpak Also some general cleanups, in particular removing domain-ontology feature which now belongs in tracker-miners.git, and can be documented there with an example app. See: https://gitlab.gnome.org/GNOME/tracker/-/issues/236 --- .../libtracker-sparql/libtracker-sparql-docs.xml | 1 - docs/reference/libtracker-sparql/overview.xml | 60 +++++++++-- docs/reference/libtracker-sparql/private-store.xml | 113 --------------------- 3 files changed, 53 insertions(+), 121 deletions(-) delete mode 100644 docs/reference/libtracker-sparql/private-store.xml diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml index 4b5793f77..792f309e7 100644 --- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml +++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml @@ -50,7 +50,6 @@ - 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 @@ Overview - 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 + + Tracker Miners filesystem indexer + , and can also store and publish any kind of app data. - Data queries and updates are done using the SPARQL graph query - language. The TrackerResource - API provides helpers for updating data. + Querying data is done using the SPARQL graph query language. See the + Examples to find out how this works. + Storing data can also be done using SPARQL, or using the + TrackerResource API. You can share a database over D-Bus using the @@ -20,24 +24,66 @@ query, or by connecting directly with tracker_sparql_connection_bus_new. + + 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 limited. + - Connection methods You can create and access a private store using tracker_sparql_connection_new. + This is useful to store app-specific data. 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 tracker_sparql_connection_bus_new. To connect to another a database on a remote machine, use tracker_sparql_connection_remote_new. + This can be used to query online databases that provide a SPARQL + endpoint, such as + DBpedia + . + + + + + Connecting from Flatpak + + + Tracker SPARQL provides a portal for the + Flatpak + application sandboxing system. This lets + you control which parts of a database each app can query. + + + The app's Flatpak manifest needs to specify which graph(s) the app will + access. See the example app + and the portal documentation + to see how. + No code changes are needed in the app, as + tracker_sparql_connection_bus_new. + will automatically try connect via the portal + if it can't talk to the given D-Bus name directly. + + + Tracker SPARQL is included in the GNOME Flatpak SDK and runtime. + If the app uses a different runtime, you may need to build Tracker SPARQL in the app manifest. + + + 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 GNOME Music + for an example of how to do this. diff --git a/docs/reference/libtracker-sparql/private-store.xml b/docs/reference/libtracker-sparql/private-store.xml deleted file mode 100644 index c598173ac..000000000 --- a/docs/reference/libtracker-sparql/private-store.xml +++ /dev/null @@ -1,113 +0,0 @@ - - - - Isolating tracker-store clients - - - Every user of tracker_sparql_connection_get() or tracker_sparql_connection_get_async() - relies on an external tracker-store instance to maintain the database, and possibly - on additional tracker miners to write the data consumed by the application. - - - Traditionally there has been only a single instance of tracker-store and miners, - shared by all consumers of Tracker data. With Tracker 2.0 it became possible to let - clients spawn their own sets of these services. - - - - - Defining a private domain ontology - - In order to make Tracker aware of this private setup, a domain ontology rule - must be dropped by the application on $(datadir)/tracker/domain-ontologies/, - the file name will be usually the DBus name or application ID of the client - prepended by ".rule", eg. org.example.App.rule - - - The following example would allow org.example.App to set up a private set - of services to index the filesystem. - - -[DomainOntology] -# All locations accept -# 1) Paths relative from a variable, the variables -# may be: HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR, -# XDG_DESKTOP_DIR, XDG_DOCUMENTS_DIR, XDG_DOWNLOAD_DIR, -# XDG_MUSIC_DIR, XDG_PICTURES_DIR, XDG_PUBLICSHARE_DIR, -# XDG_VIDEOS_DIR. -# -# eg. $XDG_CACHE_HOME/... -# -# 2) URIs -# -# eg. file:///var/... -# - -# Location for the Tracker database (not optional) -CacheLocation=$XDG_CACHE_HOME/example-app - -# Location for the data journal, used in data recovery -# situations (optional) -JournalLocation=$XDG_DATA_HOME/example-app/journal - -# Name of the ontology to use, must be one located in -# $(sharedir)/tracker/ontologies -OntologyName=nepomuk - -# DBus name for the owner (not optional). Tracker will use -# the domain as the prefix of the DBus name for all the -# services related to this domain ontology. -# -# eg. org.gnome.Photos -Domain=org.example.App - -# Miners that the domain ontology will require. This is -# purely a hint (mainly for libtracker-control), and not -# any sort of white list. Anything else knowing about this -# domain ontology may still perform updates, miners and -# non-miners. -Miners=Miner.Files;Miner.Extract; - - - The client could then instruct Tracker libraries to use - this private set up through the following call: - - -tracker_sparql_connection_set_domain ("org.example.App"); - - - It is also possible to pass a full path to the domain rule. If the first - character of the domain name is / it will be treated as a full path. - - - - Additional precautions and recommendations - - In order to work flawlessly with the created services, the - client must adopt some precautions that were optional in the - past, but now have become mandatory. - - - Use TrackerNotifier to receive notifications - - Listening directly to the GraphUpdated DBus signal will yield - the wrong results, since it relies on the DBus name adopted by - the default tracker-store service. - - - - Use TrackerMinerManager to ensure services are started - - The miner lifetime has been traditionally unclear, being those - usually deemed a system service that would usually be there. - When using private services that assumption can't hold true, - so the client is responsible for ensuring those services are - started. - - - Note that this is the recommended behavior anyway even if the - client were not to use private services. - - - - -- cgit v1.2.1