1librasqal(3) Library Functions Manual librasqal(3)
2
6 librasqal - Rasqal RDF query library
7
9 #include <rasqal.h>
10 rasqal_init();
12 rasqal_query_results *results;
13 raptor_uri *base_uri=raptor_new_uri("http://example.org/foo");
14 rasqal_query *rq=rasqal_new_query("rdql",NULL);
15 const char *query_string="select * from <http://example.org/data.rdf>";
16 rasqal_query_prepare(rq,query_string,base_uri);
18 results=rasqal_query_execute(rq);
19 while(!rasqal_query_results_finished(results)) {
20 for(i=0;i<rasqal_query_results_get_bindings_count(results);i++) {
21 const char *name=rasqal_query_results_get_binding_name(results,i);
22 rasqal_literal *value=rasqal_query_results_get_binding_value(results,i);
23 /* ... */
24 }
25 rasqal_query_results_next(results);
26 }
27 rasqal_free_query_results(results);
28 rasqal_free_query(rq);
29 raptor_free_uri(base_uri);
30 rasqal_finish();
31 cc `rasqal-config --cflags` file.c `rasqal-config --libs`
33
35 The Rasqal library provides a high-level interface to RDF query pars‐
36 ing, query construction, query execution over an RDF graph and query
37 results manipulation and formatting. The library provides APIs to each
38 of the steps in the process and provides support for handling multiple
39 query language syntaxes. At present Rasqal partially supports the W3C
40 draft SPARQL query language and fully supports RDQL.
41 Rasqal uses the libraptor(3) library for providing URI handling, WWW
43 content retrieval and other support functions.
44
46 rasqal_init()
47 rasqal_finish()
49 Initialise and cleanup the library. These must be called before
50 any Rasqal class is created or used.
51
53 These functions provide general library features not associated to any
54 particular class.
55 int rasqal_languages_enumerate(const unsigned int counter, const char
57 **name, const char **label, const unsigned char **uri_string)
58 Return the name, label, uri_string (all optional) for a query
59 language with a given integer counter, returning non-zero if no
60 such query language at that offset exists. The counter should
61 start from 0 and be incremented by 1 until the function returns
62 non-zero.
63 int rasqal_language_name_check(const char *name)
65 Check name is a known query language name.
66 int rasqal_query_set_feature(rasqal_query* query, rasqal_feature fea‐
68 ture, int value)
69 Set a query feature feature to a particular integer value.
70 Returns non 0 on failure or if the feature is unknown. The cur‐
71 rent defined parser features are:
72 Feature Values
73 RASQAL_FEATURE_NO_NET Boolean (non 0 true)
74 If the no_net feature is true (default false) then network requests are
76 denied.
77 int rasqal_query_set_feature_string(rasqal_query* query, rasqal_feature
79 feature, const unsigned char* value)
80 Set a query feature feature to a particular string value.
81 Returns non 0 on failure or if the feature is unknown. The cur‐
82 rent defined query features are given in rasqal_query_set_fea‐
83 ture and at present only take integer values. If an integer
84 value feature is set with this function, value is interpreted as
85 an integer and then that value is used.
86 int rasqal_query_get_feature(rasqal_query* query, rasqal_feature fea‐
88 ture)
89 Get a query feature integer value. The allowed feature values
90 and types are given under rasqal_features_enumerate.
91 const unsigned char* rasqal_query_get_feature_string(rasqal_query*
93 query, rasqal_feature feature)
94 Get a query feature string value. The allowed feature values and
95 types are given under rasqal_features_enumerate.
96 int rasqal_features_enumerate(const rasqal_feature feature, const
98 char** name, raptor_uri** uri, const char** label)
99 Return the name, URI, string label (all optional) for a query
100 feature, returning non-zero if no such feature exists.
101 unsigned int rasqal_get_feature_count(void)
103 Get the count of rasqal features defined which can be found with
104 rasqal_features_enumerate.
105 Rasqal features have URIs that are constructed from the URI http://fea‐
107 ture.librdf.org/rasqal- and the name so for example feature noNet has
108 URI http://feature.librdf.org/rasqal-noNet
109 rasqal_feature rasqal_feature_from_uri(raptor_uri* uri)
111 Turn a URI uri into a rasqal feature identifier, or <0 if the
112 feature is unknown. The URIs are described below
113 rasqal_query_set_feature.
114 int rasqal_feature_value_type(const rasqal_feature feature)
116 Get a rasqal feature value tyype - integer or string.
117
119 rasqal_query* rasqal_new_query(const char *name, const unsigned char
120 *uri)
121 Create a new rasqal query object for the query syntax with name
122 name. Currently "rdql" for the RDF Data Query Language and
123 "sparql" for the SPARQL query language are recognised. A lan‐
124 guage may alternatively be identified by a URI uri. If name and
125 uri are both NULL the default query language is selected, cur‐
126 rently "sparql".
127
129 void rasqal_free_query(rasqal_query* query)
130 Destroy a rasqal query object.
131
133 const char* rasqal_query_get_name(rasqal_query* query)
134 Get the query language name.
135 const char* rasqal_query_get_label(rasqal_query* query)
137 Get the query language human readable label.
138 void rasqal_query_set_fatal_error_handler(rasqal_query* query, void
140 *user_data, raptor_message_handler handler)
141 Set the fatal error handler callback.
142 void rasqal_query_set_error_handler(rasqal_query* query, void
144 *user_data, raptor_message_handler handler)
145 Set the error handler callback.
146 void rasqal_query_set_warning_handler(rasqal_query* query, void
148 *user_data, raptor_message_handler handler)
149 Set the warning handler callback.
150 int rasqal_query_get_distinct(rasqal_query* query)
152 Get the query distinct mode flag as described in
153 rasqal_query_set_distinct()
154 void rasqal_query_set_distinct(rasqal_query* query, int mode)
156 Set the query distinct results mode: 0 (none), 1 (SPARQL DIS‐
157 TINCT) or 2 (SPARQL REDUCE).
158 int rasqal_query_get_limit(rasqal_query* query)
160 Get the query-specified limit on results returning >= 0 if a
161 limit is given, otherwise not specified.
162 void rasqal_query_set_limit(rasqal_query* query, int limit)
164 Set the query results limit. No more than limit results will be
165 returned.
166 int rasqal_query_get_offset(rasqal_query* query)
168 Get the query-specified offset on results returning >= 0 if a
169 offset is given, otherwise not specified.
170 void rasqal_query_set_offset(rasqal_query* query, int offset)
172 Set the query results offset. The first offset results will be
173 not be returned.
174 void rasqal_query_add_variable(rasqal_query* query, rasqal_variable*
176 var)
177 Add a variable binding to the sequence of bindings in the query.
178 raptor_sequence* rasqal_query_get_bound_variable_sequence(rasqal_query*
180 query)
181 Get the sequence of variables that are returning bindings in the
182 query such as when explicitly chosen via SELECT in RDQL or
183 SPARQL or all variables mentioned with SELECT *.
184 raptor_sequence* rasqal_query_get_all_variable_sequence(rasqal_query*
186 query)
187 Get the sequence of all variables mentioned in the query.
188 rasqal_variable* rasqal_query_get_variable(rasqal_query* query, int
190 idx)
191 Get one variable binding in the sequence of variable bindings in
192 the query.
193 raptor_sequence* rasqal_query_get_anonymous_vari‐
195 able_sequence(rasqal_query* query)
196 Get the raptor_sequence of anonymous variables mentioned in the
197 query.
198 int rasqal_query_has_variable(rasqal_query* query, const unsigned char
200 *name)
201 Return non-0 if the named variable is in the variable bindings
202 of the query.
203 int rasqal_query_set_variable(rasqal_query* query, const unsigned char
205 *name, rasqal_literal* value)
206 Set the query variable name to a literal value (the variable
207 must already be in the sequence of variable bindings).
208 raptor_sequence* rasqal_query_get_triple_sequence(rasqal_query* query)
210 Get the sequence of triples to match in the query.
211 rasqal_triple* rasqal_query_get_triple(rasqal_query* query, int idx)
213 Get one triple in the sequences of triples to match in the
214 query.
215 void rasqal_query_add_prefix(rasqal_query* query, rasqal_prefix* pre‐
217 fix)
218 Add one namespace prefix/URI to the sequence of prefixes in the
219 query.
220 raptor_sequence* rasqal_query_get_prefix_sequence(rasqal_query* query)
222 Get the sequence of prefixes in the query.
223 rasqal_prefix* rasqal_query_get_prefix(rasqal_query* query, int idx)
225 Get one prefix in the sequence of prefixes in the query at index
226 idx.
227 raptor_sequence* rasqal_query_get_graph_pattern_sequence(rasqal_query*
229 query)
230 Get the sequence of graph patterns expressions in the query.
231 rasqal_graph_pattern* rasqal_query_get_graph_pattern(rasqal_query*
233 query, int idx)
234 Get a graph pattern in the sequence of graph_pattern expressions
235 in the query.
236 void rasqal_query_print(rasqal_query* query, FILE* stream)
238 Print a query in a debug format. This format may change in any
239 release.
240 int rasqal_query_prepare(rasqal_query* query, const unsigned char
242 *query_string, raptor_uri *base_uri)
243 Prepare a query string query_stringwith optional base URI
244 uri_string for execution, parsing it and modifying the
245 rasqal_query internals. Return non-0 on failure.
246 rasqal_query_results* rasqal_query_execute(rasqal_query* query)
248 Execute a query, returning a rasqal_query_results* object or
249 NULL on failure.
250 void rasqal_query_set_user_data(rasqal_query* query, void *user_data)
252 Set some user data to be associated with the query.
253 void* rasqal_query_get_user_data(rasqal_query* query)
255 Get the user data associated with the query.
256 int rasqal_query_add_data_graph(rasqal_query* query, raptor_uri* uri,
258 raptor_uri* name_uri, int flags)
259 Add a data graph to the query's data sources, constructing a new
260 data graph object with URI uri, optional name URI name_uri and
261 flags. See rasqal_new_data_graph for a description of the
262 argumetns.
263 raptor_sequence* rasqal_query_get_data_graph_sequence(rasqal_query*
265 query)
266 Get the sequence of data graphs in the query.
267 rasqal_data_graph* rasqal_query_get_data_graph(rasqal_query* query, int
269 idx)
270 Get one prefix in the sequence of prefixes in the query at index
271 idx.
272 raptor_sequence* rasqal_query_get_order_condi‐
274 tions_sequence(rasqal_query* query)
275 Get the sequence of all result ordering conditions in the query,
276 each of which is a rasqal_expression.
277 rasqal_expression* rasqal_query_get_order_condition(rasqal_query*
279 query, int idx)
280 Get one result ordering condition expression in the sequence.
281 rasqal_query_verb rasqal_query_get_verb(rasqal_query* query)
283 Get the main query verb.
284 int rasqal_query_get_wildcard(rasqal_query* query)
286 Get the query verb wildcard flag signifying * in RDQL and SPARQL
287 after the query verb.
288 rasqal_graph_pattern* rasqal_query_get_query_graph_pat‐
290 tern(rasqal_query* query)
291 Get the top query graph pattern of query.
292 void rasqal_query_set_default_generate_bnodeid_parameters(rasqal_query*
294 rdf_query, char* prefix, int base)
295 Control the default method for generation of IDs for blank
296 nodes. The method uses a short string prefix and an integer
297 base to generate the identifier which is not guaranteed to be a
298 strict concatenation. If prefix is NULL, the default is used.
299 If base is less than 1, it is initialised to 1.
300 void rasqal_query_set_generate_bnodeid_handler(rasqal_query* query,
302 void* user_data, rasqal_generate_bnodeid_handler handler)
303 Allow full customisation of the generated IDs by setting a call‐
304 back handler and associated user_data that is called whenever a
305 blank node or bag identifier is required. The memory returned
306 is deallocated inside rasqal. Some systems require this to be
307 allocated inside the same library, in which case the
308 rasqal_alloc_memory function may be useful.
309 rasqal_query_verb_as_string(rasqal_query_verb verb)
311 Get a string for the query verb.
312 raptor_sequence* rasqal_query_get_con‐
314 struct_triples_sequence(rasqal_query* query)
315 Get the sequence of triples for a construct.
316 rasqal_triple* rasqal_query_get_construct_triple(rasqal_query* query,
318 int idx)
319 Get a triple in the sequence of construct triples.
320 int rasqal_query_get_explain(rasqal_query* query)
322 Get whether explain was given in the query.
323 raptor_sequence* rasqal_query_get_group_condi‐
325 tions_sequence(rasqal_query* query)
326 Get the sequence of result group bys in the graph pattern.
327 rasqal_expression* rasqal_query_get_group_condition(rasqal_query*
329 query, int idx)
330 Get one group by expression in the sequences of result group bys
331 in the graph pattern at index idx.
332 int rasqal_query_write(raptor_iostream* iostr, rasqal_query* query,
334 raptor_uri* format_uri, raptor_uri* base_uri)
335 Write a formatted query to a raptor iostream iostr in format
336 described by URI format_uri using base URI base_uri for relative
337 URIs (or NULL).
338 int rasqal_query_iostream_write_escaped_counted_string(rasqal_query*
340 query, raptor_iostream* iostr, const unsigned char* string, size_t len)
341 Write a string to an iostream in an escaped form suitable for
342 the query string. Uses rasqal_query_escape_counted_string to
343 perform the escaping.
344 unsigned char* rasqal_query_escape_counted_string(rasqal_query* query,
346 const unsigned char *string, size_t len, size_t* output_len_p)
347 Convert a string of length len into an escaped form suitable for
348 the query string. If output_len is not NULL, it is a pointer to
349 the location to store the output string lenght. The returned
350 string must be freed by the caller with rasqal_free_memory.
351
353 A class for graph patterns in a query - a set of triple patterns) with
354 flags and possible sub-graph patterns
355
357 There is no public constructor for this class, it is constructed when
358 the query is prepared from a syntax. The query methods
359 rasqal_query_get_graph_pattern_sequence and rasqal_query_get_graph_pat‐
360 tern provide access to the top-level graph patterns in a query.
361 rasqal_triple* rasqal_graph_pattern_get_triple(rasqal_graph_pattern*
363 graph_pattern, int idx)
364 Get a rasqal_triple inside a graph pattern at index idx return‐
365 ing NULL when the index is out of range.
366 void rasqal_graph_pattern_add_sub_graph_pattern(rasqal_graph_pattern*
368 graph_pattern, rasqal_graph_pattern* sub_graph_pattern)
369 Add a sub-graph pattern sub_graph_pattern to the sequence of
370 sub-graph patterns inside the graph pattern.
371 raptor_sequence* rasqal_graph_pattern_get_sub_graph_pat‐
373 tern_sequence(rasqal_graph_pattern* graph_pattern)
374 Get the sequence of sub-graph patterns inside the graph pattern
375 returning NULL if there are no sub-graph patterns.
376 rasqal_graph_pattern* rasqal_graph_pattern_get_sub_graph_pat‐
378 tern(rasqal_graph_pattern* graph_pattern, int idx)
379 Get a sub-graph pattern inside the graph pattern at index idx
380 returning NULL when the index is out of range.
381 rasqal_graph_pattern_operator rasqal_graph_pattern_get_opera‐
383 tor(rasqal_graph_pattern* graph_pattern)
384 Get the graph pattern operator to determine how the graph pat‐
385 tern should be interpreted.
386 int rasqal_graph_pattern_get_flags(rasqal_graph_pattern* graph_pattern)
388 Deprecated. Use rasqal_graph_pattern_get_operator instead.
389 int rasqal_graph_pattern_add_constraint(rasqal_graph_pattern* gp,
391 rasqal_expression* expr)
392 Add a constraint expression expr to the sequence of constraints
393 in the graph pattern.
394 raptor_sequence* rasqal_graph_pattern_get_con‐
396 straint_sequence(rasqal_graph_pattern* gp)
397 Get the sequence of constraints in the graph pattern.
398 rasqal_expression* rasqal_graph_pattern_get_con‐
400 straint(rasqal_graph_pattern* gp, int idx)
401 Get one constraint expression in the sequences of constraint to
402 match in the graph pattern at index idx.
403 int rasqal_graph_pattern_get_index(rasqal_graph_pattern* graph_pattern)
405 Get the graph pattern absolute index in the array of graph pat‐
406 terns. The index is assigned when rasqal_query_prepareP is run
407 on the query containing the graph pattern.
408 void rasqal_graph_pattern_print(rasqal_graph_pattern* graph_pattern,
410 FILE* fh)
411 Print a graph pattern in a debug format. This format may change
412 in any release.
413 const char* rasqal_graph_pattern_operator_as_string(rasqal_graph_pat‐
415 tern_operator op)
416 Utility function to get a graph pattern operator as a string.
417 int rasqal_graph_pattern_visit(rasqal_graph_pattern* graph_pattern,
419 rasqal_graph_pattern_visit_fn fn, void *user_data)
420 Visit a user function fn recursively over the graph pattern and
421 it's sub-graph patterns. The order is the first graph pattern
422 at hand and then the arguments, if any. function fn is called
423 at each point with the arguments of user_data and the graph pat‐
424 tern.
425
427 A class for the results of a query. The results can be in different
428 formats - variable bindings, RDF graphs as a sequence of triples or a
429 boolean result. The format returned is determined by the query which
430 is query-language specific.
431
433 There is no public constructor for this class, the
434 rasqal_query_results* is returned from rasqal_query_execute.
435
437 rasqal_free_query_results(rasqal_query_results *query_results)
438 Destroy a rasqal query results object.
439
441 int rasqal_query_results_is_bindings(rasqal_query_results*
442 query_results)
443 int rasqal_query_results_is_boolean(rasqal_query_results*
445 query_results)
446 int rasqal_query_results_is_graph(rasqal_query_results* query_results)
448 int rasqal_query_results_is_syntax(rasqal_query_results*
450 query_results);
451 Return non-0 if the rasqal_query_results is of the given format.
452 Only one of these will be non-0 for any result.
453 int rasqal_query_results_write(raptor_iostream *iostr,
455 rasqal_query_results *results, raptor_uri *format_uri, raptor_uri
456 *base_uri)
457 Write the query results in a syntax to the iostr iostream, the
458 format of the syntax is given by the format_uri URI, with an
459 optional base URI base_uri that may be used. The values of for‐
460 mat_uri supported are provided by at runtime by the function
461 rasqal_query_results_formats_enumerate(). This uses the
462 librdf_query_results_formatter class internally.
463
465 int rasqal_query_results_get_count(rasqal_query_results *query_result)
466 Get the current number of variable bindings results returned.
467 (Variable bindings results only)
468 int rasqal_query_results_next(rasqal_query_results *query_results)
470 Move to the next variable bindings result, returning non-0 on
471 failure or results are exhausted. (Variable bindings results
472 only)
473 int rasqal_query_results_finished(rasqal_query_results *query_results)
475 Find out if the variable binding results are exhausted, return
476 non-0 if results are finished or the query failed. (Variable
477 bindings results only)
478 int rasqal_query_results_get_bindings(rasqal_query_results
480 *query_results, const unsigned char ***names, rasqal_literal ***values)
481 Get all variable binding names and values for the current
482 result. If names is not NULL, it is set to the address of a
483 shared array of names of the bindings (an output parameter). If
484 values is not NULL, it is set to the address of a shared array
485 of rasqal_literal* binding values. Note that both the names or
486 values are shared and must not be freed by the caller. Returns
487 non-0 if the assignment failed. (Variable bindings results only)
488 rasqal_literal* rasqal_query_results_get_bind‐
490 ing_value(rasqal_query_results *query_results, int offset)
491 Get one variable binding literal value for the current result.
492 Returns the value of the variable indexed in the sequence of
493 variable bindings at position offset. (Variable bindings results
494 only)
495 const unsigned char* rasqal_query_results_get_bind‐
497 ing_name(rasqal_query_results *query_results, int offset)
498 Get the name of the variable indexed in the sequence of variable
499 bindings at position offset. (Variable bindings results only)
500 rasqal_literal* rasqal_query_results_get_bind‐
502 ing_value_by_name(rasqal_query_results *query_results, const unsigned
503 char *name)
504 Get the value of the variable in the sequence of variable bind‐
505 ings named name or NULL if not known or unbound. (Variable bind‐
506 ings results only)
507 int rasqal_query_results_get_bindings_count(rasqal_query_results
509 *query_results)
510 Get the number of bound variables in the variable bindings
511 result or <0 on failure. (Variable bindings results only)
512
514 int rasqal_query_results_get_boolean(rasqal_query_results
515 *query_results)
516 Return the value of a boolean query result. This is meaningless
517 if the query result is not a boolean. (Boolean result format
518 only).
519
521 raptor_statement* rasqal_query_results_get_triple(rasqal_query_results
522 *query_results)
523 Return the current triple in the RDF graph results or NULL at
524 end of results or on failure. The returned raptor_statement is
525 a shared pointer. (Graph results format only).
526 int rasqal_query_results_next_triple(rasqal_query_results
528 *query_results)
529 Move to the next triple in the RDF graph results, returning
530 non-0 at end of results or on failure. (Graph results format
531 only).
532
534 A class for formatting the results of a query into a syntax.
535
537 rasqal_query_results_formatter* rasqal_new_query_results_format‐
538 ter(const char *name, raptor_uri* uri)
539 Create a new query results formatter for the name or uri. The
540 rasqal_query_results_formats_enumerate() function returns the
541 allowed names and/or uris. If name and uri are both NULL, the
542 default query results format is used.
543 rasqal_query_results_formatter* rasqal_new_query_results_format‐
545 ter_by_mime_type(const char *mime_type)
546 Create a new query results formatter for the output mime_type.
547 The rasqal_query_results_formats_enumerate_full() function
548 returns the allowed names, uris and mime types.
549 rasqal_query_results_formatter_get_mime_type() can return the
550 mime type of a constructed object.
551
553 void rasqal_free_query_results_formatter(rasqal_query_results_format‐
554 ter* formatter)
555 Destroy a rasqal query results formatter object.
556
558 int rasqal_query_results_formatter_write(raptor_iostream* iostr,
559 rasqal_query_results_formatter* formatter, rasqal_query_results*
560 results, raptor_uri* base_uri)
561 Write the query results formatted in a syntax to the iostr
562 iostream an optional base URI base_uri.
563 const char* rasqal_query_results_format‐
565 ter_get_mime_type(rasqal_query_results_formatter* formatter)
566 Get the mime type of the selected formatter.
567
569 int rasqal_query_results_formats_enumerate(const unsigned int counter,
570 const char** name, const char** label, const unsigned char**
571 uri_string)
572 Get query results formats information by counter. When counter
573 is 0, this returns the default query results format. The name,
574 label and/or uri_string may be returned if they are not NULL.
575 int rasqal_query_results_formats_enumerate_full(const unsigned int
577 counter, const char **name, const char **label, const unsigned char
578 **uri_string, const char **mime_type)
579 Get query results formats information by counter.. When counter
580 is 0, this returns the default query results format. The name,
581 label, uri_string and/or mime_type may be returned if they are
582 not NULL.
583 int rasqal_query_results_formats_check(const char *name, raptor_uri*
585 uri, const char *mime_type)
586 Check if a query results formatter with the given name, uri or
587 mime_type exists, as would be used by the constructors
588 rasqal_new_query_results_formatter() or
589 rasqal_new_query_results_formatter_by_mime_type() if called.
590
592 A class for the values returned as parts of triples and in variable
593 bindings. The rasqal_literal structure is public and defined in
594 rasqal.h however note that some fields are used for different literal
595 types in different ways. The types of literals are defined in the
596 rasqal_literal_type enum.
597
599 There a several constructors for rasqal_literal to build them from sim‐
600 ple types and existing rasqal_literal objects. NOTE: Any objects or
601 strings passed into these constructors becomed owned by the literal
602 object except where noted.
603 rasqal_literal* rasqal_new_decimal_literal(const unsigned char* deci‐
605 mal)
606 Create a new decimal literal from string decimal.
607 rasqal_literal* rasqal_new_double_literal(double d)
609 Create a new double literal from a d.
610 rasqal_literal* rasqal_new_integer_literal(rasqal_literal_type type,
612 int integer)
613 Create a new integer literal of an integral type, either type
614 RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN.
615 rasqal_literal* rasqal_new_floating_literal(double f)
617 DEPRECATED. Use rasqal_new_double_literal. Create a new float‐
618 ing literal from a f.
619 rasqal_literal* rasqal_new_uri_literal(raptor_uri* uri)
621 Create a new URI literal from a raptor_uri uri.
622 rasqal_literal* rasqal_new_pattern_literal(const unsigned char *pat‐
624 tern, const char *flags)
625 Create a new regular expression literal from regex pattern and
626 flags.
627 rasqal_literal* rasqal_new_string_literal(const unsigned char *string,
629 const char *language, raptor_uri *datatype, const unsigned char
630 *datatype_qname)
631 Create a new Rasqal string literal. The datatype and
632 datatype_qname parameters are alternatives; the QName is a
633 datatype that cannot be resolved till later since the prefixes
634 have not yet been declared or checked at the time this construc‐
635 tor is called.
636 If the string literal is datatyped and of certain types recog‐
638 nised (currently xsd:decimal, xsd:double) it may be internally
639 converted to a different literal type.
640 rasqal_literal* rasqal_new_simple_literal(rasqal_literal_type type,
642 const unsigned char *string)
643 Create a new Rasqal simple literal of type RASQAL_LITERAL_BLANK
644 or RASQAL_LITERAL_BLANK_QNAME.
645 rasqal_literal* rasqal_new_boolean_literal(int value)
647 Create a new Raqal boolean literal, where value is non-0 for
648 true, 0 for false.
649 rasqal_literal* rasqal_new_variable_literal(rasqal_variable* variable)
651 Create a new Rasqal variable literal using an existing variable
652 object.
653
655 rasqal_literal* rasqal_new_literal_from_literal(rasqal_literal* lit‐
656 eral)
657 Copy an existing literal object.
658
660 void rasqal_free_literal(rasqal_uri* literal)
661 Destroy a rasqal literal object.
662
664 void rasqal_literal_print(rasqal_literal* literal, FILE* fh)
665 Print a literal in a debug format. This format may change in
666 any release.
667 rasqal_variable* rasqal_literal_as_variable(rasqal_literal* literal)
669 Return a rasqal literal as a variable, if it is one, otherwise
670 return NULL.
671 const unsigned char* rasqal_literal_as_string(rasqal_literal* literal)
673 Return a rasqal literal as a string value. This always suc‐
674 ceeds. Return a rasqal literal as a string value according to
675 flags. The only defined string value at present is RASQAL_COM‐
676 PARE_XQUERY to use XQuery conversion rules. If error is not
677 NULL, it will be set to non-0 if there is an error.
678 rasqal_literal* rasqal_literal_as_node(rasqal_literal* literal)
680 Return a new rasqal literal into one suitable for a node in an
681 RDF triple or binding - as a URI, literal string (or datatyped)
682 or blank node. The returned literal is owned by the caller and
683 must be freed by rasqal_free_literal.
684 int rasqal_literal_compare(rasqal_literal* literal1, rasqal_literal*
686 literal2, rasqal_compare_flags flags, int* error)
687 Compare two literals with type promotion across their range. If
688 the types are not the same, they are promoted. If one is a
689 floating, the other is promoted to floating, otherwise for inte‐
690 gers, otherwise as strings (all literals have a string value).
691 flags affects string comparisons. If the RASQAL_COMPARE_NOCASE
693 bit is set, a case independent comparison is made.
694 The return value is comparable to strcmp(3), first before second
696 returns <0. equal returns 0, and first after second returns >0.
697 If there is no ordering, such as for URIs, the return value is 0
698 for equal, non-0 for different (using raptor_uri_equals).
699 int rasqal_literal_equals(rasqal_literal* literal1, rasqal_literal*
701 literal2)
702 Compare two literals with no type promotion If literal2's value
703 is a boolean, it will match
704 the string "true" or "false" in literal1.
705
707 A class for triples of three literals, used for matching triples in a
708 query where the literals may be variables as well as in then interface
709 between Rasqal and RDF systems using RDF triples, when the literals may
710 not be literals. The structure of this class is public and defined in
711 rasqal.h
712
714 rasqal_triple* rasqal_new_triple(rasqal_literal* subject, rasqal_lit‐
715 eral* predicate, rasqal_literal* object)
716 Create a new rasqal triple from three literals.
717
719 rasqal_triple* rasqal_new_triple_from_triple(rasqal_triple* triple)
720 Copy an existing rasqal triple object.
721
723 void rasqal_free_triple(rasqal_triple* triple)
724 Destroy a rasqal triple object.
725
727 void rasqal_triple_print(rasqal_triple* triple, FILE* fh)
728 Print a triple in a debug format. This format may change in any
729 release.
730 void rasqal_triple_set_origin(rasqal_triple* triple, rasqal_literal
732 *literal)
733 Set the origin rasqal_literal of the triple, typically a URI
734 literal.
735 rasqal_literal* rasqal_triple_get_origin(rasqal_triple* triple)
737 Get the origin rasqal_literal of the triple.
738 void rasqal_triple_set_flags(rasqal_triple* triple, unsigned int flags)
740 DEPRECATED in rasqal 0.9.9+. Do not use.
741 unsigned int rasqal_triple_get_flags(rasqal_triple* triple)
743 DEPRECATED in rasqal 0.9.9+. Do not use.
744
746 A class for variable name and literal used to capture a variable with
747 optional value binding such as returned as query results by various
748 methods. The structure of this class is public and defined in rasqal.h
749
751 rasqal_variable* rasqal_new_variable(rasqal_query* query, const
752 unsigned char *name, rasqal_literal* value)
753 Create a new rasqal variable scoped to a Rasqal query, with
754 required name and optional rasqal_literal value. This creates a
755 variable of type RASQAL_VARIABLE_TYPE_NORMAL.
756 rasqal_variable* rasqal_new_variable_typed(rasqal_query* rq,
758 rasqal_variable_type type, const unsigned char *name, rasqal_literal*
759 value)
760 Create a new rasqal variable scoped to a Rasqal query, with
761 required name, optional rasqal_literal value and type type
762 either RASQAL_VARIABLE_TYPE_NORMAL or RASQAL_VARI‐
763 ABLE_TYPE_ANONYMOUS
764
766 void rasqal_free_variable(rasqal_variable* variable)
767 Destroy a rasqal variable object.
768
770 void rasqal_variable_print(rasqal_variable* variable, FILE* fh)
771 Print a variable in a debug format. This format may change in
772 any release.
773 void rasqal_variable_set_value(rasqal_variable* variable, rasqal_lit‐
775 eral* literal)
776 Set the value of a rasqal variable to an rasqal_literal value,
777 freeing any current value. The new literal may be NULL.
778
780 A class for namespace name/URI prefix association used to shorten URIs
781 in some query languages using XML-style QNames. The structure of this
782 class is public and defined in rasqal.h
783
785 rasqal_prefix* rasqal_new_prefix(const unsigned char* prefix, rap‐
786 tor_uri* uri)
787 Create a new namespace prefix with the given short prefix and
788 URI uri.
789
791 void rasqal_free_prefix(rasqal_prefix* prefix)
792 Destroy a rasqal prefix object.
793 void rasqal_prefix_print(rasqal_prefix* prefix, FILE* fh)
795 Print a prefix in a debug format. This format may change in any
796 release.
797
799 A class for constraint expressions over literals and variables. The
800 expression operators are defined in rasqal.h as enum rasqal_op and take
801 one, two or more complex parameters.
802
804 rasqal_expression* rasqal_new_0op_expression(rasqal_op op)
805 Create a new expression with a 0-argument operator.
806 rasqal_expression* rasqal_new_1op_expression(rasqal_op op,
808 rasqal_expression* arg)
809 Create a new expression with a 1-argument operator.
810 rasqal_expression* rasqal_new_2op_expression(rasqal_op op,
812 rasqal_expression* arg1, rasqal_expression* arg2)
813 Create a new expression with a 2-argument operator.
814 rasqal_expression* rasqal_new_2op_expression(rasqal_op op,
816 rasqal_expression* arg1, rasqal_expression* arg2, rasqal_expression*
817 arg3)
818 Create a new expression with a 3-argument operator.
819 rasqal_expression* rasqal_new_string_op_expression(rasqal_op op,
821 rasqal_expression* arg1, rasqal_literal* literal)
822 Create a new expression with a 2-argument operator, the second
823 of which is a literal string.
824 rasqal_expression* rasqal_new_literal_expression(rasqal_literal* lit‐
826 eral)
827 Create a new expression over an existing rasqal literal.
828 rasqal_expression* rasqal_new_variable_expression(rasqal_variable*
830 variable)
831 Create a new expression over an existing rasqal variable.
832 rasqal_expression* rasqal_new_function_expression(raptor_uri* name,
834 raptor_sequence* args)
835 Create a new expression for a function named name and with
836 sequence of rasqal_literal* arguments args.
837 rasqal_expression* rasqal_new_cast_expression(raptor_uri* name,
839 rasqal_expression* value)
840 Create a new expression for a casting of value to a datatype
841 with URI name.
842
844 rasqal_expression* rasqal_new_expression_from_expression(rasqal_expres‐
845 sion* expression)
846 Copy an existing rasqal expression object.
847
849 void rasqal_free_expression(rasqal_expression* expression)
850 Destroy a rasqal expression object.
851
853 void rasqal_expression_print_op(rasqal_expression* expression, FILE*
854 fh)
855 Print an expression operator in a debug format. This format may
856 change in any release.
857 void rasqal_expression_print(rasqal_expression* expression, FILE* fh)
859 Print an expression in a debug format. This format may change
860 in any release.
861 rasqal_literal* rasqal_expression_evaluate(rasqal_query* query,
863 rasqal_expression* expression, rasqal_compare_flags flags)
864 Evalute an expression, returning a rasqal boolean with the
865 result or NULL on failure. If flags are RASQAL_COMPARE_XQUERY
866 then XQuery comparison and type promotions are used.
867 int rasqal_expression_visit(rasqal_expression* expression,
869 rasqal_expression_visit_fn fn, void *user_data)
870 Visit a user function fn recursively over the expression and
871 it's sub-expressions. The order is the first expression at hand
872 and then the arguments, if any. function fn is called at each
873 point with the arguments of user_data and the expression.
874 int rasqal_expression_foreach(rasqal_expression* expression,
876 rasqal_expression_foreach_fn fn, void *user_data)
877 DEPRECATED. Use rasqal_expression_visit instead.
878 Apply the function fn recursively over the expression and it's
880 sub-expressions. The order is the first expression at hand and
881 then the arguments, if any. function fn is called at each point
882 with the arguments of user_data and the expression.
883
885 A class for graph data sources to query over from a source URI with an
886 optional name URI.
887
889 rasqal_data_graph* rasqal_new_data_graph(raptor_uri* uri, raptor_uri*
890 name_uri, int flags)
891 Create a new data graph with source URI uri and optional name
892 URI name_uri. Flags can be RASQAL_DATA_GRAPH_NONE,
893 RASQAL_DATA_GRAPH_NAMED or RASQAL_DATA_GRAPH_BACKGROUND.
894
896 void rasqal_free_data_graph(rasqal_data_graph* dg)
897 Destroy a rasqal data_graph object.
898 void rasqal_data_graph_print(rasqal_data_graph* dg, FILE* fh)
900 Print a data graph in a debug format. This format may change in
901 any release.
902
904 0.9.14
905 Added rasqal_new_0op_expression.
906 Added rasqal_new_query_results_formatter_by_mime_type and
908 rasqal_query_results_formatter_get_mime_type.
909 Added rasqal_query_results_formats_check and rasqal_query_results_for‐
911 mats_enumerate_full.
912 Added 0y_results_is_syntax.
914 Added query results group by accessor methods:
916 rasqal_query_get_group_conditions_sequence and
917 rasqal_query_get_group_condition for LAQRS.
918 rasqal_query_set_distinct now takes a mode argument.
920 Added new query verbs RASQAL_QUERY_VERB_DELETE and
922 RASQAL_QUERY_VERB_INSERT for LAQRS.
923 Added rasqal_query_get_explain
925 rasqal_expression structure looses an unused field variable.
927 Added rasqal_expression types RASQAL_EXPR_GROUP_COND_ASC,
929 RASQAL_EXPR_GROUP_COND_DESC, RASQAL_EXPR_COUNT and RASQAL_EXPR_VARSTAR
930 for LAQRS.
931 rasqal_variable structure gains a new field expression for LAQRS..
933 Added static variables rasqal_license_string and rasqal_home_url_string
935 0.9.13
937 Added rasqal_feature system with single feature RASQAL_FEATURE_NO_NET
938 and functions rasqal_feature_from_uri, rasqal_feature_value_type,
939 rasqal_features_enumerate, rasqal_get_feature_count,
940 rasqal_query_get_feature, rasqal_query_get_feature_string,
941 rasqal_query_set_feature and rasqal_query_set_feature_string. int.
942 Added rasqal_query_results_formatter class with constructor
944 rasqal_new_query_results_formatter destructor
945 rasqal_free_query_results_formatter and method
946 rasqal_query_results_formatter_write.
947 Added rasqal_query_results_formats_enumerate for listing supported for‐
949 mats.
950 0.9.12
952 Added rasqal_query_iostream_write_escaped_counted_string and
953 rasqal_query_escape_counted_string
954 Added rasqal_query_get_anonymous_variable_sequence
956 Added rasqal_graph_pattern_get_index
958 Added RASQAL_EXPR_REGEX to rasqal_op
960 Added arg3 field to rasqal_expression for the REGEX operation.
962 Added rasqal_query_write
964 Added rasqal_new_3op_expression
966 Added rasqal_literal_as_string_flags
968 0.9.11
970 Added enum rasqal_compare_flags flags for rasqal_expression_evaluate or
971 rasqal_literal_compare.
972 Function rasqal_expression_evaluate gains a flag argument.
974 Added rasqal_expression_visit and type for visitor function
976 rasqal_expression_visit_fn.
977 Added rasqal_new_expression_from_expression.
979 Deprecated rasqal_expression_foreach, replaced by rasqal_expres‐
981 sion_visit.
982 Remove unused rasqal_new_variable_expression prototype.
984 Added rasqal_graph_pattern_visit and type for visitor function
986 rasqal_graph_pattern_visit_fn.
987 Added rasqal_new_decimal_literal.
989 Deprecated rasqal_new_floating_literal replaced by new rasqal_new_dou‐
991 ble_literal.
992 Added rasqal_op type RASQAL_EXPR_LANGMATCHES for SPARQL langMatches().
994 Added rasqal_literal types: RASQAL_LITERAL_DECIMAL, RASQAL_LIT‐
996 ERAL_DATETIME, RASQAL_LITERAL_DOUBLE (replacing deprecated RASQAL_LIT‐
997 ERAL_FLOATING) and RASQAL_LITERAL_FLOAT.
998 Reordered the rasqal_literal types in the enum.
1000 0.9.10
1002 Added an rasqal_graph_pattern_operator enumerated type. with the fol‐
1003 lowing (useful) values: RASQAL_GRAPH_PATTERN_OPERATOR_BASIC (for triple
1004 patterns), RASQAL_GRAPH_PATTERN_OPERATOR_OPTIONAL (for SPARQL
1005 OPTIONAL), RASQAL_GRAPH_PATTERN_OPERATOR_UNION, RASQAL_GRAPH_PAT‐
1006 TERN_OPERATOR_GROUP and RASQAL_GRAPH_PATTERN_OPERATOR_GRAPH (for SPARQL
1007 GRAPH).
1008 Added graph pattern method rasqal_graph_pattern_get_operator Deprecated
1010 rasqal_graph_pattern_get_flags replaced by the above. Added helper
1011 function rasqal_graph_pattern_operator_as_string.
1012 Modified the type of the final argument of rasqal_new_graph_pat‐
1014 tern_from_sequence and rasqal_graph_pattern_add_triples from an integer
1015 to a rasqal_graph_pattern_operator enumeration.
1016 Removed documentation of removed functions deprecated in 0.9.9.
1018 0.9.9
1020 Added query methods rasqal_query_get_construct_triple,
1021 rasqal_query_get_construct_triples_sequence, rasqal_query_get_offset,
1022 rasqal_query_get_order_condition, rasqal_query_get_order_condi‐
1023 tions_sequence, rasqal_query_get_query_graph_pattern,
1024 rasqal_query_get_verb, rasqal_query_get_wildcard.
1025 rasqal_query_set_default_generate_bnodeid_parameters,
1026 rasqal_query_set_distinct, rasqal_query_set_generate_bnodeid_handler,
1027 rasqal_query_set_limit and rasqal_query_set_offset.
1028 Added expressions RASQAL_EXPR_ORDER_COND_ASC,
1030 RASQAL_EXPR_ORDER_COND_DESC and RASQAL_EXPR_ORDER_COND_NONE.
1031 Added enum rasqal_variable_type for typing variables.
1033 Added variable constructor rasqal_new_variable_typed to create typed
1035 variables.
1036 Added enum rasqal_query_verb for the main query verbs with values
1038 RASQAL_QUERY_VERB_SELECT, RASQAL_QUERY_VERB_CONSTRUCT
1039 RASQAL_QUERY_VERB_DESCRIBE and RASQAL_QUERY_VERB_ASK.
1040 Added rasqal_query_verb_as_string to get a strign for a query verb.
1042 Deprecated the rasqal_triple flags field and the triple methods
1044 rasqal_triple_set_flags and rasqal_triple_get_flags.
1045 0.9.8
1047 Added a Data Graph class with constructor rasqal_new_data_graph,
1048 destructor rasqal_free_data_graph and debug method
1049 rasqal_data_graph_print.
1050 Added casting expressions with type RASQAL_EXPR_CAST and expression
1052 constructor rasqal_new_cast_expression
1053 Added a no-arg graph pattern constructor rasqal_new_graph_pattern
1055 Added graph pattern methods rasqal_graph_pattern_add_triples to add
1057 triples to a graph pattern and rasqal_graph_pattern_add_sub_graph_pat‐
1058 tern to add a sub-graph pattern to a graph pattern.
1059 Added graph pattern methods rasqal_graph_pattern_add_constraint,
1061 rasqal_graph_pattern_get_constraint_sequence and rasqal_graph_pat‐
1062 tern_get_constraint to add constraints to a graph pattern.
1063 Added query methods for data graphs: rasqal_query_add_data_graph,
1065 rasqal_query_get_data_graph_sequence, rasqal_query_get_data_graph.
1066 Deprecated query methods: rasqal_query_add_constraint,
1068 rasqal_query_get_constraint_sequence rasqal_query_get_constraint,
1069 rasqal_query_add_source, rasqal_query_get_source_sequence and
1070 rasqal_query_get_source.
1071 Removed deprecated query methods: rasqal_query_get_variable_sequence
1073 and rasqal_query_add_triple.
1074 0.9.7
1076 Export rasqal_graph_pattern typedef for graph patterns and added access
1077 methods: rasqal_query_get_graph_pattern_sequence
1078 rasqal_query_get_graph_pattern, rasqal_graph_pattern_get_triple,
1079 rasqal_graph_pattern_get_sub_graph_pattern_sequence, rasqal_graph_pat‐
1080 tern_get_sub_graph_pattern, rasqal_graph_pattern_get_flags
1081 and exported previously internal rasqal_graph_pattern_print Export
1082 rasqal_pattern_flags enum for graph pattern flags.
1083 Added rasqal_query_get_bound_variable_sequence and
1085 rasqal_query_get_all_variable_sequence.
1086 Deprecate rasqal_query_get_variable_sequence prefering
1088 rasqal_query_get_bound_variable_sequence
1089 Added rasqal_query_get_distinct and rasqal_query_get_limit to get
1091 access to query flags.
1092 Deleted RASQAL_EXPR_PATTERN which was never used.
1094 0.9.6
1096 Added new 1-argument expressions to the expression constructor;
1097 rasqal_op enum gained the following values: RASQAL_EXPR_LANG,
1098 RASQAL_EXPR_DATATYPE, RASQAL_EXPR_BOUND, RASQAL_EXPR_ISURI,
1099 RASQAL_EXPR_ISBLANK and RASQAL_EXPR_ISLITERAL
1100 Added user-defined function expressions to the expression constructor:
1102 rasqal_op enum gained RASQAL_EXPR_FUNCTION value; rasqal_expression
1103 gained name and args fields and added rasqal_new_function_expression to
1104 construct a function expression.
1105 Added rasqal_query_results_is_bindings, rasqal_query_results_is_boolean
1107 and rasqal_query_results_is_graph to test the format of query result.
1108 Added rasqal_query_results_get_boolean to get the value of a boolean
1110 query result.
1111 Added rasqal_query_results_get_triple and
1113 rasqal_query_results_next_triple to return an RDF graph query result.
1114 Added rasqal_new_triple_from_triple triple copy constructor.
1116 0.9.5
1118 Added rasqal_query_results_write to format query results into a syntax,
1119 written to a raptor iostream.
1120 Changed rasqal_new_floating_literal to take a double argument.
1122 Added flags for triples with rasqal_triple_get_flags and
1124 rasqal_triple_set_flags to get and set them.
1125 Added rasqal_triple_parts enum and updated the bind_match factory
1127 method of the rasqal_triples_match structure to take and return them.
1128 Added a rasqal_triple_parts type field parts to the rasqal_triple_meta
1130 structure
1131 0.9.4
1133 No API changes.
1134 0.9.3
1136 The struct rasqal_prefix gained a declared field.
1137 The struct rasqal_triple gained an origin field; not used at present
1139 but intended to support work on tracking triple provenance such as pro‐
1140 vided by Redland Contexts.
1141 Added methods rasqal_triple_set_origin and rasqal_triple_get_origin to
1143 support the above.
1144 struct rasqal_triple_meta now takes a 4-array of bindings, the fourth
1146 being the origin.
1147 Exported function rasqal_set_triples_source_factory publically as
1149 intended.
1150 0.9.2
1152 Several functions changed their parameters or return values from char*
1153 to unsigned char* or const unsigned char* to reflect the actual use.
1154 Changed to return a const unsigned char*:
1156 rasqal_literal_as_string
1157 Changed to take const unsigned char* (or add const):
1159 rasqal_new_floating_literal
1160 rasqal_new_pattern_literal
1161 rasqal_new_prefix
1162 rasqal_new_simple_literal
1163 rasqal_new_string_literal
1164 rasqal_new_variable
1165 rasqal_query_has_variable
1166 rasqal_query_results_get_binding_name
1167 rasqal_query_results_get_binding_value_by_name
1168 rasqal_query_results_get_bindings
1169 rasqal_query_set_variable
1170 0.9.1
1172 Added the rasqal_query_results class and moved the results methods from
1173 rasqal_query.
1174 Made rasqal_query_execute return a rasqal_query_result*.
1176 Renamed all rasqal_query*result* methods to be rasqal_query_result_*
1178 Added rasqal_free_query_results to tidy up.
1179 OLD API (0.9.0) NEW API (0.9.1+)
1181 rasqal_query_get_result_count rasqal_query_results_get_count
1182 rasqal_query_next_result rasqal_query_results_next
1183 rasqal_query_results_finished rasqal_query_results_finished
1184 rasqal_query_get_result_bindings rasqal_query_results_get_bind‐
1185 ings
1186 rasqal_query_get_result_binding_value rasqal_query_results_get_bind‐
1187 ing_value
1188 rasqal_query_get_result_binding_name rasqal_query_results_get_bind‐
1189 ing_name
1190 rasqal_query_get_result_binding_by_name rasqal_query_results_get_bind‐
1191 ing_value_by_name
1192 rasqal_query_get_bindings_count rasqal_query_results_get_bind‐
1193 ings_count
1194 0.9.0
1196 All new.
1197
1199 SPARQL Query Language for RDF, Eric Prud'hommeaux and Andy Seaborne
1200 (eds), W3C Candidate Recommendation, 6 April 2006.
1201 http://www.w3.org/TR/2006/CR-rdf-sparql-query-20060406/
1202 ⟨http://www.w3.org/TR/2006/CR-rdf-sparql-query-20060406/⟩
1203 SPARQL Query Results XML Format, Jeen Broekstra and Dave Beckett (eds),
1205 W3C Candidate Recommendation, 6 April 2006.
1206 http://www.w3.org/TR/2006/CR-rdf-sparql-XMLres-20060406/
1207 ⟨http://www.w3.org/TR/2006/CR-rdf-sparql-XMLres-20060406/⟩
1208 RDQL - A Query Language for RDF, Andy Seaborne, W3C Member Submission 9
1210 January 2004 http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/
1211 ⟨http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/⟩
1212
1214 roqet(1),rasqal-config(1)
1215
1217 Dave Beckett - http://purl.org/net/dajobe/
1218 ⟨http://purl.org/net/dajobe/⟩
1219 2007-04-22 librasqal(3)