Module: Jena::Query

Defined in:
lib/jena.rb,
lib/jena/query_utils.rb

Class Method Summary collapse

Class Method Details

.as_bindings(b) ⇒ Object

Return the given bindings object as a ‘QuerySolutionsMap`. Convert a hash to a `QuerySolutionsMap` if necessary



102
103
104
105
106
107
108
109
110
 
# File 'lib/jena/query_utils.rb', line 102

def self.as_bindings( b )
  return nil unless b
  return b if b.is_a? com.hp.hpl.jena.query.QuerySolutionMap
  qsm = com.hp.hpl.jena.query.QuerySolutionMap.new
  b.each_pair do |k,v|
    qsm.add k, v
  end
  qsm
end

.describe(m, query, options = nil) ⇒ Array

Perform a SPARQL describe query. Options as per #select, but this call returns a ‘Model`.

Parameters:

  • m (Model) —

    The model to run the query against

  • query (String) —

    The query to run

  • options (Hash) (defaults to: nil) —

    Options (see above)

Returns:

  • (Array) —

    Non-empty array of hashes, one per result



73
74
75
 
# File 'lib/jena/query_utils.rb', line 73

def self.describe( m, query, options = nil )
  describe_qe( setup_query_execution( m, query, options ) )
end

.describe_qe(qexec) ⇒ Object

Perform a describe query using the given query execution object, and return the resulting model



79
80
81
82
83
84
85
 
# File 'lib/jena/query_utils.rb', line 79

def self.describe_qe( qexec )
  begin
    return qexec.execDescribe
  ensure
    qexec.close
  end
end

.has_option?(options, opt) ⇒ Boolean

Returns:

  • (Boolean) 


185
186
187
 
# File 'lib/jena/query_utils.rb', line 185

def self.has_option?( options, opt )
  options && options.has_key?( opt )
end

.option(options, opt, default) ⇒ Object 



181
182
183
 
# File 'lib/jena/query_utils.rb', line 181

def self.option( options, opt, default )
  if has_option?( options, opt ) then options[opt] else default end
end

.project_variables(soln, *vars) ⇒ Object

Project variables from a result set entry, returning a ‘Hash` of variable names to values



89
90
91
92
93
94
95
96
97
98
 
# File 'lib/jena/query_utils.rb', line 89

def self.project_variables( soln, *vars )
  nn = Hash.new

  vs = vars || []
  soln.varNames.each {|v| vs << v} if vs.empty?

  vs.each {|v| nn[v.to_sym] = soln.get( v )}

  nn
end

.select(m, query, options = nil, *vars) ⇒ Array

Perform a SPARQL select query against the given model. Returns an array of result objects, where each result is a Hash from query variable name to value.

By default, all variables from the query are returned. To return just a subset of the query variables, pass the variable name(s) as the last argument to the call.

Various options are supported:

  • ‘:ns` - a `PrefixMapping` or hash of prefixes to URI’s

  • ‘:bindings` - a `QuerySolutionMap` or hash of existing var name to value pairs

Examples

Jena.querySelect( m, 'select * where {?s ?p ?o}' )
Jena.querySelect( m, 'select * where {?s ?p ?o}', {}, "s" )
Jena.querySelect( m, 'select * where {?s ?p foo:bar}',
  {:ns => {"foo" => "http://example.com/foo#"}}, "s" )

Parameters:

  • m (Model) —

    The model to run the query against

  • query (String) —

    The query to run

  • options (Hash) (defaults to: nil) —

    Options (see above)

  • *vars (String) —

    Optional variables to project from results

Returns:

  • (Array) —

    Non-nil array of hashes, one per result



26
27
28
29
30
 
# File 'lib/jena/query_utils.rb', line 26

def self.select( m, query, options = nil, *vars )
  results = []
  select_each( m, query, options, *vars ) {|soln| results << soln}
  results
end

.select_each(m, query, options = nil, *vars, &block) ⇒ Object

Perform a select query as per #select, but rather than accumulate an array of results, we yield to the associated block with each solution



50
51
52
 
# File 'lib/jena/query_utils.rb', line 50

def self.select_each( m, query, options = nil, *vars, &block )
  select_each_qe( setup_query_execution( m, query, options ), *vars, &block )
end

.select_each_qe(qexec, *vars) ⇒ Object

Perform a select query using the given query execution, yielding to the associated block for each solution



56
57
58
59
60
61
62
63
64
 
# File 'lib/jena/query_utils.rb', line 56

def self.select_each_qe( qexec, *vars )
  begin
    qexec.execSelect.each do |soln|
      yield( project_variables( soln, *vars ) )
    end
  ensure
    qexec.close
  end
end

.select_first(m, query, options = nil, *vars) ⇒ Object

Perform a select query as per #select, but returns only the first result, if defined, or nil



34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/jena/query_utils.rb', line 34

def self.select_first( m, query, options = nil, *vars )
  qexec = setup_query_execution( m, query, options )
  result = nil

  begin
    rs = qexec.execSelect
    result = project_variables( rs.next, *vars ) if rs.hasNext
  ensure
    qexec.close
  end

  result
end

.service_describe(url, query) ⇒ Object

Return a model from a describe query against a remote SPARQL endpoint



154
155
156
 
# File 'lib/jena/query_utils.rb', line 154

def self.service_describe( url, query )
  describe_qe( sparql_service( url, query ) )
end

.service_select(url, query, *vars) ⇒ Object

Return a list of the solutions to executing the given select query against the given remote SPARQL endpoint



141
142
143
144
145
 
# File 'lib/jena/query_utils.rb', line 141

def self.service_select( url, query, *vars )
  results = []
  select_each_qe( sparql_service( url, query ), *vars ) {|soln| results << soln}
  results
end

.service_select_each(url, query, *vars, &block) ⇒ Object

Yield to the associated block for each solution to the given query against the given SPARQL service endpoint URL



149
150
151
 
# File 'lib/jena/query_utils.rb', line 149

def self.service_select_each( url, query, *vars, &block )
  select_each_qe( sparql_service( url, query ), *vars, &block )
end

.setup_query_execution(m, query, options) ⇒ Object

Common part of setting up a query execution



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/jena/query_utils.rb', line 190

def self.setup_query_execution( m, query, options )
  q = com.hp.hpl.jena.query.Query.new

  q.setPrefixMapping has_option?( options, :ns ) ? Util::as_prefix_map( options[:ns] ) : useful_prefixes

  baseURI = option( options, :baseURI, nil )
  syntax = option( options, :syntax, com.hp.hpl.jena.query.Syntax.syntaxSPARQL_11 )

  QueryFactory.parse( q, query, baseURI, syntax )
  bindings = as_bindings( option( options, :bindings, nil ) )

  bindings ? QueryExecutionFactory.create( q, m, bindings ) : QueryExecutionFactory.create( q, m )
end

.sparql_format(value) ⇒ Object

Format a given value in a manner suitable for inclusion in a SPARQL query



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/jena/query_utils.rb', line 159

def self.sparql_format( value )
  if value.is_a? Core::Resource
    value.is_anon ? "_:#{value.get_id.to_string.gsub(/[^[[:alnum:]]]/, '_')}" : "<#{value.get_uri}>"
  elsif value.is_a? Core::Literal
    if dt = value.get_datatype_uri
      "\"#{value.get_lexical_form}\"^^<#{dt}>"
    else
      "\"#{value.to_string}\""
    end
  elsif value.to_s =~ /\A(file|http):\/\//
    "<#{value}>"
  elsif value.to_s =~ /\A[-_[[:alnum:]]]*:/
    # looks like a qname
    value.to_s
  else
    # guess
    "\"#{value.to_s}\""
  end
end

.sparql_service(url, query) ⇒ Object

Return a QueryExecution for executing the given query against a remote SPARQL service endpoint



135
136
137
 
# File 'lib/jena/query_utils.rb', line 135

def self.sparql_service( url, query )
  Jena::Query::QueryExecutionFactory.sparqlService( url, query )
end

.useful_prefixes ⇒ Object

A mutable collection of well-known namespace prefixes, which can be used as a basis for building up a larger collection



114
115
116
117
118
 
# File 'lib/jena/query_utils.rb', line 114

def self.useful_prefixes
  pm = com.hp.hpl.jena.shared.impl.PrefixMappingImpl.new
  pm.setNsPrefixes( com.hp.hpl.jena.shared.PrefixMapping.Standard )
  pm
end

.valid?(query_string, syntax = Jena::Query::Syntax.syntaxSPARQL_11) ⇒ Boolean

Return true if a string represents a valid SPARQL query.

Returns:

  • (Boolean) 


121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/jena/query_utils.rb', line 121

def self.valid?( query_string, syntax = Jena::Query::Syntax.syntaxSPARQL_11 )
  q = Jena::Query::QueryFactory.create

  begin
    Jena::Query::QueryFactory.parse( q, query_string, nil, syntax )
    return true
  rescue
  end

  false
end