librasqal − Rasqal RDF query library |
#include <rasqal.h> rasqal_init(); rasqal_query_results *results; raptor_uri *base_uri=raptor_new_uri("http://example.org/foo"); rasqal_query *rq=rasqal_new_query("rdql",NULL); const char *query_string="select * from <http://example.org/data.rdf>"; rasqal_query_prepare(rq,query_string,base_uri); results=rasqal_query_execute(rq); while(!rasqal_query_results_finished(results)) { for(i=0;i<rasqal_query_results_get_bindings_count(results);i++) { const char *name=rasqal_query_results_get_binding_name(results,i); rasqal_literal *value=rasqal_query_results_get_binding_value(results,i); /* ... */ } rasqal_query_results_next(results); } rasqal_free_query_results(results); rasqal_free_query(rq); raptor_free_uri(base_uri); rasqal_finish(); cc ‘rasqal-config --cflags‘ file.c ‘rasqal-config --libs‘ |
The Rasqal library provides a high-level interface to RDF query parsing, query construction and query execution over an RDF graph. The library provides APIs to each of the steps in the process and provides support for handling multiple query language syntaxes. At present rasqal supports RDQL and the draft W3C SPARQL query language. Rasqal uses the libraptor(3) library for providing URI handling, WWW content retrieval and other support functions. |
rasqal_init() |
rasqal_finish() |
Initialise and cleanup the library. These must be called before any Rasqal class is created or used. |
These functions provide general library features not associated to any particular class. |
int rasqal_languages_enumerate(const unsigned int counter, const char **name, const char **label, const unsigned char **uri_string) |
Return the name, label, uri_string (all optional) for a query language with a given integer counter, returning non-zero if no such query language at that offset exists. The counter should start from 0 and be incremented by 1 until the function returns non-zero. |
int rasqal_language_name_check(const char *name) |
Check name is a known query language name. |
rasqal_query* rasqal_new_query(const char *name, const unsigned char *uri) |
Create a new rasqal query object for the query syntax with name name currently only "rdql" for the RDF Data Query Language. A language may alternatively be identified by a URI uri. |
void rasqal_free_query(rasqal_query* query) |
Destroy a rasqal query object. |
const char* rasqal_query_get_name(rasqal_query* query) |
Get the query language name. |
const char* rasqal_query_get_label(rasqal_query* query) |
Get the query language human readable label. |
void rasqal_query_set_fatal_error_handler(rasqal_query* query, void *user_data, raptor_message_handler handler) |
Set the fatal error handler callback. |
void rasqal_query_set_error_handler(rasqal_query* query, void *user_data, raptor_message_handler handler) |
Set the error handler callback. |
void rasqal_query_set_warning_handler(rasqal_query* query, void *user_data, raptor_message_handler handler) |
Set the warning handler callback. |
void rasqal_query_set_feature(rasqal_query *query, rasqal_feature feature, int Ivalue) |
Set a query feature feature to a particular value. Returns non 0 on failure or if the feature is unknown. No current features are defined. |
void rasqal_query_add_source(rasqal_query* query, raptor_uri* Iuri) |
Add a source URI to the sequence of sources in the query. |
raptor_sequence* rasqal_query_get_source_sequence(rasqal_query* query) |
Get the sequence of sources in the query. |
raptor_uri* rasqal_query_get_source(rasqal_query* query, int Iidx) |
Get one source in the sequence of sources in the queyr. |
void rasqal_query_add_variable(rasqal_query* query, rasqal_variable* Ivar) |
Add a variable binding to the sequence of bindings in the query. |
raptor_sequence* rasqal_query_get_variable_sequence(rasqal_query* query) |
Get the sequence of variable bindings in the query. |
rasqal_variable* rasqal_query_get_variable(rasqal_query* query, int Iidx) |
Get one variable binding in the sequence of variable bindings in the queyr. |
int rasqal_query_has_variable(rasqal_query* query, const unsigned char *name) |
Return non-0 if the named variable is in the variable bindings of the query. |
int rasqal_query_set_variable(rasqal_query* query, const unsigned char *name, rasqal_literal* value); |
Set the query variable name to a literal value (the variable must already be in the sequence of variable bindings). |
void rasqal_query_add_triple(rasqal_query* query, rasqal_triple* triple); |
Add a triple to the sequence of triples to match in the query. |
raptor_sequence* rasqal_query_get_triple_sequence(rasqal_query* query) |
Get the sequence of triples to match in the query. |
rasqal_triple* rasqal_query_get_triple(rasqal_query* query, int Iidx) |
Get one triple in the sequences of triples to match in the query. |
void rasqal_query_add_constraint(rasqal_query* query, rasqal_expression* expr); |
Add a constraint expression to the sequence of constraints in the query. |
raptor_sequence* rasqal_query_get_constraint_sequence(rasqal_query* query) |
Get the sequence of constraints in the query. |
rasqal_expression* rasqal_query_get_constraint(rasqal_query* query, int Iidx) |
Get one constraint expression in the sequences of constraint to match in the query. |
void rasqal_query_add_prefix(rasqal_query* query, rasqal_prefix* prefix); |
Add one namespace prefix/URI to the sequence of prefixes in the query. |
raptor_sequence* rasqal_query_get_prefix_sequence(rasqal_query* query) |
Get the sequence of prefixes in the query. |
rasqal_prefix* rasqal_query_get_prefix(rasqal_query* query, int Iidx) |
Get one prefix in the sequence of prefixes in the query. |
void rasqal_query_print(rasqal_query *query, FILE *stream); |
Print a query in a debug format. This format may change in any release. |
int rasqal_query_prepare(rasqal_query* query, const unsigned char *query_string, raptor_uri *base_uri); |
Prepare aquery string query_stringwith optional base URI uri_string for execution, parsing it and modifying the rasqal_query internals. Return non-0 on failure. |
rasqal_query_results* rasqal_query_execute(rasqal_query* query) |
Execute a query, returning a rasqal_query_results* object or NULL on failure. |
void rasqal_query_set_user_data(rasqal_query *query, void *user_data) |
Set some user data to be associated with the query. |
void* rasqal_query_get_user_data(rasqal_query *query) |
Get the user data associated with the query. |
A class for the results of a query. The results can be in different forms, presently variable bindings are available but graphs or sets of graphs may be returned as sets of triples, a triple at a time. |
There is no public constructor for this class, the rasqal_query_results* is returned from rasqal_query_execute. |
rasqal_free_query_results(rasqal_query_results *query_results); |
Destroy a rasqal query results object. |
int rasqal_query_results_get_count(rasqal_query_results *query_result) |
Get the current number of results returned. |
int rasqal_query_results_next(rasqal_query_results *query_results) |
Move to the next result, returning non-0 on failure or results are exhausted. |
int rasqal_query_results_finished(rasqal_query_results *query_results) |
Find out if binding results are exhausted, return non-0 if results are finished or the query failed. |
int rasqal_query_results_get_bindings(rasqal_query_results *query_results, const unsigned char ***names, rasqal_literal ***values); |
Get all binding names and values for the current result. If names is not NULL, it is set to the address of a shared array of names of the bindings (an output parameter). If values is not NULL, it is set to the address of a shared array of rasqal_literal* binding values. Note that both the names or values are shared and must not be freed by the caller. Returns non-0 if the assignment failed. |
rasqal_literal* rasqal_query_results_get_binding_value(rasqal_query_results *query_results, int offset); |
Get one binding literal value for the current result. Returns the value of the variable indexed in the sequence of variable bindings at position offset. |
const unsigned char* rasqal_query_results_get_binding_name(rasqal_query_results *query_results, int offset); |
Get the name of the variable indexed in the sequence of variable bindings at position offset. |
rasqal_literal* rasqal_query_results_get_binding_value_by_name(rasqal_query_results *query_results, const unsigned char *name) |
Get the value of the variable in the sequence of variable bindings named name or NULL if not known or unbound. |
int rasqal_query_results_get_bindings_count(rasqal_query_results *query_results) |
Get the number of bound variables in the result or <0 on failure. |
A class for the values returned as parts of triples and in variable bindings. The rasqal_literal structure is public and defined in rasqal.h however note that some fields are used for different literal types in different ways. The types of literals are defined in the rasqal_literal_type enum. |
There a several constructors for rasqal_literal to build them from simple types and existing rasqal_literal objects. NOTE: Any objects or strings passed into these constructors becomed owned by the literal object except where noted. |
rasqal_literal* rasqal_new_integer_literal(rasqal_literal_type type, int integer) |
Create a new integer literal of an integral type, either type RASQAL_LITERAL_INTEGER or RASQAL_LITERAL_BOOLEAN. |
rasqal_literal* rasqal_new_floating_literal(const unsigned char *string) |
Create a new floating literal from a string form of the double. |
rasqal_literal* rasqal_new_uri_literal(raptor_uri* uri) |
Create a new URI literal from a raptor_uri uri. |
rasqal_literal* rasqal_new_pattern_literal(const unsigned char *pattern, const char *flags) |
Create a new regular expression literal from regex pattern and flags. |
rasqal_literal* rasqal_new_string_literal(const unsigned char *string, const char *language, raptor_uri *datatype, const unsigned char *datatype_qname) |
Create a new Rasqal string literal. The datatype and datatype_qname parameters are alternatives; the QName is a datatype that cannot be resolved till later since the prefixes have not yet been declared or checked at the time this constructor is called. |
If the string literal is datatyped and of certain types recognised (currently xsd:decimal, xsd:double) it may be internally converted to a different literal type. |
rasqal_literal* rasqal_new_simple_literal(rasqal_literal_type type, const unsigned char *string) |
Create a new Rasqal simple literal of type RASQAL_LITERAL_BLANK or RASQAL_LITERAL_BLANK_QNAME. |
rasqal_literal* rasqal_new_boolean_literal(int value) |
Create a new Raqal boolean literal, where value is non-0 for true, 0 for false. |
rasqal_literal* rasqal_new_variable_literal(rasqal_variable* variable) |
Create a new Rasqal variable literal using an existing variable object. |
rasqal_literal* rasqal_new_literal_from_literal(rasqal_literal* literal) |
Copy an existing literal object. |
void rasqal_free_literal(rasqal_uri* literal) |
Destroy a rasqal literal object. |
void rasqal_literal_print(rasqal_literal* literal, FILE* fh) |
Print a literal in a debug format. This format may change in any release. |
rasqal_variable* rasqal_literal_as_variable(rasqal_literal* Iliteral) |
Return a rasqal literal as a variable, if it is one, otherwise return NULL. |
const unsigned char* rasqal_literal_as_string(rasqal_literal* Iliteral) |
Return a rasqal literal as a string value. This always succeeds. |
rasqal_literal* rasqal_literal_as_node(rasqal_literal* Iliteral) |
Return a new rasqal literal into one suitable for a node in an RDF triple or binding - as a URI, literal string (or datatyped) or blank node. The returned literal is owned by the caller and must be freed by rasqal_free_literal. |
int rasqal_literal_compare(rasqal_literal* Iliteral1, rasqal_literal* Iliteral2, int flags, int* error) |
Compare two literals with type promotion across their range. If the types are not the same, they are promoted. If one is a floating, the other is promoted to floating, otherwise for integers, otherwise as strings (all literals have a string value). |
flags affects string comparisons and if the RASQAL_COMPARE_NOCASE bit is set, a case independent comparison is made. The return value is comparable to strcmp(3), first before second returns <0. equal returns 0, and first after second returns >0. If there is no ordering, such as for URIs, the return value is 0 for equal, non-0 for different (using raptor_uri_equals). |
int rasqal_literal_equals(rasqal_literal* Iliteral1, rasqal_literal* Idata_literal2); |
Compare two literals with no type promotion If data_literal’s value is a boolean, it will match the string "true" or "false" in literal. |
A class for triples of three literals, used for matching triples in a query where the literals may be variables as well as in then interface between Rasqal and RDF systems using RDF triples, when the literals may not be literals. The structure of this class is public and defined in rasqal.h |
rasqal_triple* rasqal_new_triple(rasqal_literal* subject, rasqal_literal* predicate, rasqal_literal* object) |
Create a new rasqal triple from three literals. |
void rasqal_free_triple(rasqal_triple* triple) |
Destroy a rasqal triple object. |
void rasqal_triple_print(rasqal_triple* triple, FILE* fh) |
Print a triple in a debug format. This format may change in any release. |
void rasqal_triple_set_origin(rasqal_triple* triple, rasqal_literal *literal) |
Set the origin rasqal_literal of the triple, typically a URI literal. |
rasqal_literal* rasqal_triple_get_origin(rasqal_triple* triple) |
Get the origin rasqal_literal of the triple. |
A class for variable name and literal used to capture a variable with optional value binding such as returned as query results by various methods. The structure of this class is public and defined in rasqal.h |
rasqal_variable* rasqal_new_variable(rasqal_query* query, const unsigned char *name, rasqal_literal* value) |
Create a new rasqal variable scoped to a Rasqal query, with required name and optional rasqal_literal value |
void rasqal_free_variable(rasqal_variable* Ivariable) |
Destroy a rasqal variable object. |
void rasqal_variable_print(rasqal_variable* variable, FILE* fh) |
Print a variable in a debug format. This format may change in any release. |
void rasqal_variable_set_value(rasqal_variable* variable, rasqal_literal* literal) |
Set the value of a rasqal variable to an rasqal_literal value, freeing any current value. The new literal may be NULL. |
A class for namespace name/URI prefix association used to shorten URIs in some query languages using XML-style QNames. The structure of this class is public and defined in rasqal.h |
rasqal_prefix* rasqal_new_prefix(const unsigned char *prefix, raptor_uri* uri) |
Create a new namespace prefix with the given short prefix and URI uri. |
void rasqal_free_prefix(rasqal_prefix* prefix) |
Destroy a rasqal prefix object. |
void rasqal_prefix_print(rasqal_prefix* prefix, FILE* fh) |
Print a prefix in a debug format. This format may change in any release. |
A class for constraint expressions over literals and variables. The expression operators are defined in rasqal.h as enum rasqal_op and take one, two or more complex parameters. |
rasqal_expression* rasqal_new_1op_expression(rasqal_op op, rasqal_expression* arg); |
Create a new expression with a 1-argument operator. |
rasqal_expression* rasqal_new_2op_expression(rasqal_op op, rasqal_expression* arg1, rasqal_expression* arg2) |
Create a new expression with a 2-argument operator. |
rasqal_expression* rasqal_new_string_op_expression(rasqal_op op, rasqal_expression* arg1, rasqal_literal* literal) |
Create a new expression with a 2-argument operator, the second of which is a literal string. |
rasqal_expression* rasqal_new_literal_expression(rasqal_literal* literal) |
Create a new expression over an existing rasqal literal. |
rasqal_expression* rasqal_new_variable_expression(rasqal_variable* variable) |
Create a new expression over an existing rasqal variable. |
void rasqal_free_expression(rasqal_expression* expression) |
Destroy a rasqal expression object. |
void rasqal_expression_print_op(rasqal_expression* expressionxpression, FILE* fh) |
Print an expression operator in a debug format. This format may change in any release. |
void rasqal_expression_print(rasqal_expression* expression, FILE* fh) |
Print an expression in a debug format. This format may change in any release. |
rasqal_literal* rasqal_expression_evaluate(rasqal_query *query, rasqal_expression* expression) |
Evalute an expression, returning a rasqal boolean with the result or NULL on failure. |
int rasqal_expression_foreach(rasqal_expression* expression, rasqal_expression_foreach_fn fn, void *user_data) |
Apply the function fn recursively over the expression and it’s sub-expressions. The order is the first expression at hand and then the arguments, if any. function fn is called at each point with the arguments of user_data and the expression. |
0.9.3 |
The struct rasqal_prefix gained a declared field. |
0.9.2 |
Several functions changed their parameters or return values from char* to unsigned char* or const unsigned char* to reflect the actual use. Changed to return a const unsigned char*: Changed to take const unsigned char* (or add const): |
0.9.1 |
Added the rasqal_query_results class and moved the results methods from rasqal_query. OLD API (0.9.0) NEW API (0.9.1+) |
0.9.0 |
All new. |
RDQL - A Query Language for RDF, Andy Seaborne, W3C Member Submission 9 January 2004 http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/ SPARQL Query Language for RDF, Eric Prud’hommeaux and Andy Seaborne (ed), W3C Working Draft, 12 October 2004. http://www.w3.org/TR/2004/WD-rdf-sparql-query-20041012/ |
roqet(1),rasqal-config(1) |
Dave Beckett |
Copyright 2002-2004 Dave Beckett, Institute for Learning and Research Technology, University of Bristol