Errors and refusals

When pgRDF can't run a query as written, it raises an error instead of returning a wrong or partial answer. Every error carries a SQLSTATE. Match on the code, not the message text. The message names the construct or graph involved, and usually the fix.

In psql, \set VERBOSITY verbose shows the code:

ERROR:  0A000: sparql: unsupported algebra in select wrapper: SERVICE (federated query)

Codes you'll meet in queries

SQLSTATE	Condition name	In queries
`0A000`	`feature_not_supported`	A construct pgRDF doesn't support, named in the message: `SERVICE`, `FILTER EXISTS` / `NOT EXISTS`, `LANGMATCHES`, a `FILTER` or `HAVING` expression it can't evaluate (`COALESCE`, `SUBSTR`, `IF`, `CONCAT`, …), a `UNION` or `FILTER` inside `MINUS`, `LOAD`.
`22023`	`invalid_parameter_value`	A bad argument: `pgrdf.construct()` given a query that isn't a `CONSTRUCT` or doesn't parse, or a template variable the `WHERE` never binds; a setting given a value outside its range, such as `SET pgrdf.path_max_depth = 0`.
`42704`	`undefined_object`	An unknown graph given to a graph function you use around queries, such as `pgrdf.clear_graph('http://example.org/nope')`. Inside SPARQL, `GRAPH <unknown>` simply matches nothing, and an `INSERT` into an unknown graph creates it.
`55P03`	`lock_not_available`	An UPDATE that would change a locked graph.
`54000`	`program_limit_exceeded`	A property path was cut short by `pgrdf.path_max_depth` while `pgrdf.on_path_truncation = 'error'`.
`XX000`	`internal_error`	See the next section.

The full list of pgRDF's codes is on Errors and diagnostics.

XX000 with a descriptive message

Some refusals still arrive as XX000. If the message starts with sparql: (or names a pgRDF function), it is a refusal of that query, just like a 0A000: change the query the way the message says.

The query uses	The message starts
A function in `BIND` or `SELECT` that pgRDF can't compute	`sparql: BIND expression for ?x not translatable: …`
A blank node (`_:b`, `[]`) or a sequence path (`p1/p2`) in a pattern	`sparql: blank-node subject in query not supported`
`UNION` inside `OPTIONAL`	`sparql: OPTIONAL group contains an unsupported sub-pattern: …`
`VALUES` binding a `GRAPH` variable	`sparql: VALUES binds ?g, which also names a GRAPH scope …`
`ORDER BY` an expression together with `DISTINCT`	`sparql: ORDER BY over an expression is not supported together with DISTINCT …`
A syntax error	`sparql: parse error: error at 1:10: …` (line and column)
`CONSTRUCT` or `DESCRIBE` passed to `pgrdf.sparql()`	`sparql: query form not supported yet …`, `sparql: use pgrdf.describe(q) for DESCRIBE queries`
`CREATE GRAPH` on an existing graph, or `DROP` / `CLEAR GRAPH` on a missing one, without `SILENT`	`sparql: CREATE GRAPH <…>: graph already exists`, `… graph not bound`

An XX000 without such a message is a genuine fault. Please report it, with the query that caused it.

Handling refusals in SQL

In PL/pgSQL, catch refusals by condition name or by code:

sql

DO $$
BEGIN
  PERFORM * FROM pgrdf.sparql(
    'SELECT * WHERE { SERVICE <http://example.org/sparql> { ?s ?p ?o } }');
EXCEPTION
  WHEN feature_not_supported THEN          -- 0A000
    RAISE NOTICE 'not supported (%): %', SQLSTATE, SQLERRM;
END $$;
-- NOTICE:  not supported (0A000): sparql: unsupported algebra in select wrapper: SERVICE (federated query)

sql

EXCEPTION
  WHEN lock_not_available THEN             -- 55P03: graph is locked
    ...
  WHEN SQLSTATE '54000' THEN               -- property path truncated
    ...

Application drivers expose the same code, for example e.code in node-postgres, e.sqlstate in psycopg, pgErr.Code in pgx and SQLException.getSQLState() in JDBC. There are examples for each on Errors and diagnostics.

Checking a query before running it

pgrdf.sparql_parse(q) lists some unsupported features in unsupported_algebra without running the query, such as SERVICE and nested property paths. It does not catch everything: expression-level refusals (FILTER NOT EXISTS, COALESCE, …) and some pattern shapes appear only when the query runs.

Partial answers are not errors

A property path that hits pgrdf.path_max_depth returns fewer rows with a WARNING, not an error, unless you set pgrdf.on_path_truncation = 'error'. See Was the answer complete?.

Errors and refusals ​

Codes you'll meet in queries ​

XX000 with a descriptive message ​

Handling refusals in SQL ​

Checking a query before running it ​

Partial answers are not errors ​