The surf.query Module

class surf.query.Filter

Bases: unicode

A SPARQL triple pattern filter

class surf.query.Group

Bases: list

A SPARQL triple pattern group

class surf.query.NamedGroup(name=None)

Bases: surf.query.Group

A SPARQL triple pattern named group

class surf.query.OptionalGroup

Bases: surf.query.Group

A SPARQL triple pattern optional group

class surf.query.Query(type, *vars)

Bases: object

The Query object is used by SuRF to construct queries in a programatic manner. The class supports the major SPARQL query types: select, ask, describe, construct. Although it follows the SPARQL format the query can be translated to other Query formats such as PROLOG, for now though only SPARQL is supported.

Query objects should not be instatiated directly, instead use module-level ask(), construct(), describe(), select() functions.

Query methods can be chained.

distinct()

Add DISTINCT modifier.

filter(filter)

Add FILTER construct to query WHERE clause.

filter must be either string/unicode or surf.query.Filter object, if it is None then no filter is appended.

from_(*uris)

Add graph URI(s) that will go in separate FROM clause.

Each argument can be either string or surf.rdf.URIRef.

from_named(*uris)

Add graph URI(s) that will go in separate FROM NAMED clause.

Each argument can be either string or surf.rdf.URIRef.

limit(limit)

Add LIMIT modifier to query.

named_group(name, *statements)

Add GROUP ?name { ... } construct to WHERE clause.

name is the variable name that will be bound to graph IRI.

*statements is one or more graph patterns.

Example:

>>> import surf
>>> from surf.query import a, select
>>> query = select("?s", "?src").named_group("?src", ("?s", a, surf.ns.FOAF['Person']))
>>> print unicode(query)
SELECT  ?s ?src  WHERE {  GRAPH ?src {  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person>  }  }    

offset(offset)

Add OFFSET modifier to query.

optional_group(*statements)

Add optional group graph pattern to WHERE clause.

optional_group() accepts multiple arguments, similarly to where().

order_by(*vars)

Add ORDER_BY modifier to query.

query_data

the query data, internal structure representing the contents of the WHERE clause

query_from

list of URIs that will go into query FROM clauses

query_from_named

list of URIs that will go into query FROM NAMED clauses

query_limit

the query limit, can be a number or None

query_modifier

the query modifier can be: DISTINCT, REDUCED, or None

query_offset

the query offset, can be a number or None

query_order_by

the query order by variables

query_type

the query type can be: SELECT, ASK, DESCRIBE*or *CONSTRUCT

query_vars

the query variables to return as the resultset

reduced()

Add REDUCED modifier.

where(*statements)

Add graph pattern(s) to WHERE clause.

where() accepts multiple arguments. Each argument represents a a graph pattern and will be added to default group graph pattern. Each argument can be tuple, list, surf.query.Query, surf.query.NamedGroup, surf.query.OptionalGroup.

Example:

>>> query = select("?s").where(("?s", a, surf.ns.FOAF["person"]))

class surf.query.Union

Bases: surf.query.Group

A SPARQL union

surf.query.ask()

Construct and return surf.query.Query object of type ASK

surf.query.construct(*vars)

Construct and return surf.query.Query object of type CONSTRUCT

surf.query.describe(*vars)

Construct and return surf.query.Query object of type DESCRIBE

surf.query.group(*statements)

Return group graph pattern.

Returned object can be used as argument in Query.where() method.

group()` accepts multiple arguments, similarly to Query.where().

surf.query.named_group(name, *statements)

Return named group graph pattern.

Returned object can be used as argument in Query.where() method.

*statements is one or more graph patterns.

Example:

>>> import surf
>>> from surf.query import a, select, named_group
>>> query = select("?s", "?src").where(named_group("?src", ("?s", a, surf.ns.FOAF['Person'])))
>>> print unicode(query)
SELECT  ?s ?src  WHERE {  GRAPH ?src {  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person>  }  }    

surf.query.optional_group(*statements)

Return optional group graph pattern.

Returned object can be used as argument in Query.where() method.

optional_group() accepts multiple arguments, similarly to Query.where().

surf.query.select(*vars)

Construct and return surf.query.Query object of type SELECT

*vars are variables to be selected.

Example:

>>> query = select("?s", "?p", "?o")

surf.query.union(*statements)

Return union graph pattern.

Returned object can be used as argument in Query.where() method.

union()` accepts multiple arguments, similarly to Query.where().