Title: Examples

This document shows some real examples of usage of the TinySPARQL
library.

## Querying a remote endpoint

All SPARQL queries happen through a [class@SparqlConnection], often
these connections represent a remote endpoints maintained by another process or
server.

This example demonstrates the use of these connections on a remote
endpoint. Concretely creating a D-Bus [class@SparqlConnection],
creating a prepared statement from a SPARQL query string, executing
the query, and obtaining the query results from the cursor.

The [method@SparqlConnection.query_statement] method can be used
to obtain a [class@SparqlStatement] object holding a prepared SPARQL
query that can then be executed with [method@SparqlStatement.execute].
The query string can contain `~name` placeholders which can be replaced with
arbitrary values before query execution with
[method@SparqlStatement.bind_string] and similar functions.
This allows parsing the query string only once and to execute it multiple
times with different parameters with potentially significant performance gains.

Multiple functions offer asynchronous variants, so the application
main loop is not blocked while these operations are executed.

Once you end up with the query, remember to call [method@SparqlCursor.close].
The same applies to [method@SparqlConnection.close] when no longer needed.

In C:
```c
{{ examples/connection-example.c }}
```

In Python:
```python
{{ examples/connection-example.py }}
```

In Javascript:
```js
{{ examples/connection-example.js }}
```

## Creating a private database

Applications may create private RDF triple stores via the [ctor@SparqlConnection.new]
constructor.

This example demonstrates the creation of a private store, for simplicity the
example uses the builtin Nepomuk ontology, but the data structures may be defined
by the application, see the documentation on
[creating custom ontologies](ontologies.html#creating-custom-ontologies) for more information about this.

The example also demonstrates the use of [class@Resource] and [class@Batch]
for insertion of RDF data. It is also possible to use [class@SparqlStatement] for
updates through the [method@Batch.add_statement] methods, or plain SPARQL strings
through [method@Batch.add_sparql].

Multiple functions offer asynchronous variants, so the application
main loop is not blocked while these operations are executed.

Once you no longer need the connection, remember to call [method@SparqlConnection.close].

In C:
```c
{{ examples/private-store-example.c }}
```

In Python:
```python
{{ examples/private-store-example.py }}
```

In Javascript:
```js
{{ examples/private-store-example.js }}
```

## Creating a SPARQL endpoint

For some applications and services, it might be desirable to export a
RDF triple store as an endpoint. Making it possible for other applications to
query the data they hold.

This example demonstrates the use of [class@Endpoint] subclasses,
concretely the creation of a D-Bus endpoint, that other applications
may query e.g. through a connection created with
[ctor@SparqlConnection.bus_new].

In C:
```c
{{ examples/endpoint-example.c }}
```

In Python:
``` python
{{ examples/endpoint-example.py }}
```

In Javascript:
```js
{{ examples/endpoint-example.js }}
```

## Receiving notification on changes

As an additional feature over SPARQL endpoints, TinySPARQL allows for
users of private and D-Bus SPARQL connections to receive notifications
on changes of certain RDF classes (Those with the
[nrl:notify](nrl-ontology.html#nrl:notify) property, like
[nmm:MusicPiece](nmm-ontology.html#nmm:MusicPiece)).

This example demonstrates the use of [class@Notifier] to receive
notifications on database updates.

In C:
```c
{{ examples/notifier-example.c }}
```

In Python:
```python
{{ examples/notifier-example.py }}
```

In Javascript:
```js
{{ examples/notifier-example.js }}
```