Class: RDF::Query
- Inherits:
-
Object
- Object
- RDF::Query
- Includes:
- Enumerable
- Defined in:
- lib/rdf/query.rb,
lib/rdf/query/pattern.rb,
lib/rdf/query/solution.rb,
lib/rdf/query/variable.rb,
lib/rdf/query/solutions.rb,
lib/rdf/query/hash_pattern_normalizer.rb
Overview
An RDF basic graph pattern (BGP) query.
Named queries either match against a specifically named
graph if the name is an RDF::Resource or bound RDF::Query::Variable.
Names that are against unbound variables match either default
or named graphs.
The name of false
will only match against the default graph.
Variable names cause the variable to be added to the solution set elements.
Defined Under Namespace
Classes: HashPatternNormalizer, Pattern, Solution, Solutions, Variable
Instance Attribute Summary collapse
-
#graph_name ⇒ RDF::Resource, ...
Scope the query to named graphs matching value.
-
#options ⇒ Hash
readonly
Any additional options for this query.
-
#patterns ⇒ Array<RDF::Query::Pattern>
readonly
The patterns that constitute this query.
-
#solutions ⇒ RDF::Query::Solutions
readonly
The solution sequence for this query.
Class Method Summary collapse
-
.execute(queryable, patterns = {}, options = {}) {|query| ... } ⇒ RDF::Query::Solutions
Executes a query on the given
queryable
graph or repository. -
.Solutions(*args) ⇒ Object
Cast values as Solutions.
Instance Method Summary collapse
-
#+(other) ⇒ RDF::Query
Add patterns from another query to form a new Query.
-
#<<(pattern)
Appends the given query
pattern
to this query. -
#apply_graph_name(graph_name = nil) ⇒ Object
Apply the graph name specified (or configured) to all patterns that have no graph name.
-
#default? ⇒ Boolean
Is this query scoped to the default graph?.
-
#dup ⇒ RDF::Query
Duplicate query, including patterns and solutions.
-
#each_solution {|solution| ... } ⇒ Enumerator
(also: #each)
Enumerates over each matching query solution.
-
#each_statement {|RDF::Query::Pattern| ... } ⇒ Enumerator
Enumerates over each statement (pattern).
-
#empty? ⇒ Boolean
Query has no patterns.
-
#execute(queryable, bindings: {}, solutions: Solution.new, graph_name: nil, name: nil, **options) {|solution| ... } ⇒ RDF::Query::Solutions
Executes this query on the given
queryable
graph or repository. -
#failed? ⇒ Boolean
Returns
true
if this query did not match when last executed. -
#initialize(*patterns, solutions: nil, graph_name: nil, name: nil, validate: false, **options, &block) ⇒ Query
constructor
Initializes a new basic graph pattern query.
-
#matched? ⇒ Boolean
Returns
true
if this query matched when last executed. -
#named? ⇒ Boolean
Is this query scoped to a named graph?.
-
#node? ⇒ Boolean
(also: #has_blank_nodes?)
Returns
true
if any pattern contains a blank node. -
#optimize(**options) ⇒ RDF::Query
Returns an optimized copy of this query.
-
#optimize!(**options) ⇒ self
Optimizes this query by reordering its constituent triple patterns according to their cost estimates.
-
#pattern(pattern, **options)
Appends the given query
pattern
to this query. -
#unnamed? ⇒ Boolean
Is this query unscoped? This indicates that it can return results from either a named graph or the default graph.
-
#valid? ⇒ Boolean
Determine if the query containts valid patterns.
-
#validate! ⇒ RDF::Query
Validate this query, making sure it can be executed by our query engine.
- #variable?(*args) ⇒ Object (also: #variables?, #has_variables?)
-
#variable_count ⇒ Integer
Returns the number of variables in this query.
-
#variables ⇒ Hash{Symbol => RDF::Query::Variable}
The variables used in this query.
Methods included from Enumerable
#canonicalize, #canonicalize!, #dump, #each_graph, #each_object, #each_predicate, #each_quad, #each_subject, #each_term, #each_triple, #enum_graph, #enum_object, #enum_predicate, #enum_quad, #enum_statement, #enum_subject, #enum_term, #enum_triple, #graph?, #graph_names, #invalid?, #method_missing, #object?, #objects, #predicate?, #predicates, #project_graph, #quad?, #quads, #respond_to_missing?, #statement?, #statements, #subject?, #subjects, #supports?, #term?, #terms, #to_a, #to_h, #to_set, #triple?, #triples
Methods included from Util::Aliasing::LateBound
Methods included from Countable
Constructor Details
#initialize(patterns = [], **options) {|query| ... } ⇒ Query #initialize(patterns, **options) ⇒ Query
Initializes a new basic graph pattern query.
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 |
# File 'lib/rdf/query.rb', line 185 def initialize(*patterns, solutions: nil, graph_name: nil, name: nil, validate: false, **, &block) @options = .dup @solutions = Query::Solutions(solutions) graph_name = name if graph_name.nil? @graph_name = graph_name patterns << @options if patterns.empty? @patterns = case patterns.first when Hash then compile_hash_patterns(HashPatternNormalizer.normalize!(patterns.first.dup, @options)) when Array then patterns.first else patterns end if block_given? case block.arity when 1 then block.call(self) else instance_eval(&block) end end validate! if validate end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class RDF::Enumerable
Instance Attribute Details
#graph_name ⇒ RDF::Resource, ...
Scope the query to named graphs matching value
141 142 143 |
# File 'lib/rdf/query.rb', line 141 def graph_name @graph_name end |
#options ⇒ Hash (readonly)
Any additional options for this query.
135 136 137 |
# File 'lib/rdf/query.rb', line 135 def @options end |
#patterns ⇒ Array<RDF::Query::Pattern> (readonly)
The patterns that constitute this query.
123 124 125 |
# File 'lib/rdf/query.rb', line 123 def patterns @patterns end |
#solutions ⇒ RDF::Query::Solutions (readonly)
The solution sequence for this query.
129 130 131 |
# File 'lib/rdf/query.rb', line 129 def solutions @solutions end |
Class Method Details
.execute(queryable, patterns = {}, options = {}) {|query| ... } ⇒ RDF::Query::Solutions
Executes a query on the given queryable
graph or repository.
92 93 94 |
# File 'lib/rdf/query.rb', line 92 def self.execute(queryable, patterns = {}, = {}, &block) self.new(patterns, **, &block).execute(queryable, **) end |
.Solutions ⇒ Solutions .Solutions(solutions) ⇒ Solutions .Solutions(array) ⇒ Solutions .Solutions(*args) ⇒ Solutions
Cast values as Solutions
111 112 113 114 115 116 117 |
# File 'lib/rdf/query.rb', line 111 def self.Solutions(*args) if args.length == 1 return args[0] if args[0].is_a?(Solutions) args = args[0] if args[0].is_a?(Array) end return Solutions.new(args) end |
Instance Method Details
#+(other) ⇒ RDF::Query
Add patterns from another query to form a new Query
416 417 418 |
# File 'lib/rdf/query.rb', line 416 def +(other) Query.new(self.patterns + other.patterns) end |
#<<(pattern)
This method returns an undefined value.
Appends the given query pattern
to this query.
215 216 217 218 |
# File 'lib/rdf/query.rb', line 215 def <<(pattern) @patterns << Pattern.from(pattern) self end |
#apply_graph_name(graph_name = nil) ⇒ Object
Apply the graph name specified (or configured) to all patterns that have no graph name
441 442 443 444 |
# File 'lib/rdf/query.rb', line 441 def apply_graph_name(graph_name = nil) graph_name ||= self.graph_name patterns.each {|pattern| pattern.graph_name = graph_name if pattern.graph_name.nil?} unless graph_name.nil? end |
#default? ⇒ Boolean
Is this query scoped to the default graph?
428 429 430 |
# File 'lib/rdf/query.rb', line 428 def default? graph_name == false end |
#dup ⇒ RDF::Query
Duplicate query, including patterns and solutions
528 529 530 531 |
# File 'lib/rdf/query.rb', line 528 def dup patterns = @patterns.map {|p| p.dup} Query.new(patterns, graph_name: graph_name, solutions: @solutions.dup, **) end |
#each_solution {|solution| ... } ⇒ Enumerator Also known as: each
Enumerates over each matching query solution.
509 510 511 |
# File 'lib/rdf/query.rb', line 509 def each_solution(&block) @solutions.each(&block) end |
#each_statement {|RDF::Query::Pattern| ... } ⇒ Enumerator
Enumerates over each statement (pattern).
520 521 522 523 |
# File 'lib/rdf/query.rb', line 520 def each_statement(&block) apply_graph_name patterns.each(&block) end |
#empty? ⇒ Boolean
Query has no patterns
498 499 500 |
# File 'lib/rdf/query.rb', line 498 def empty? patterns.empty? end |
#execute(queryable, bindings: {}, solutions: Solution.new, graph_name: nil, name: nil, **options) {|solution| ... } ⇒ RDF::Query::Solutions
solutions could be an Iterator, but this algorithm cycles over solutions, which requires them to be an array internally.
Executes this query on the given queryable
graph or repository.
Named queries either match against a specifically named
graphs if the name is an RDF::Resource or bound RDF::Query::Variable.
Names that are against unbound variables match either detault
or named graphs.
The name of false
will only match against the default graph.
If the query nas no patterns, it returns a single empty solution as per SPARQL 1.1 Empty Group Pattern.
311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
# File 'lib/rdf/query.rb', line 311 def execute(queryable, bindings: {}, solutions: Solution.new, graph_name: nil, name: nil, **, &block) # Use provided solutions to allow for query chaining # Otherwise, a quick empty solution simplifies the logic below; no special case for # the first pattern @solutions = Query::Solutions(solutions) bindings = bindings.to_h if bindings.is_a?(Solution) # If there are no patterns, just return the empty solution if empty? @solutions.each(&block) if block_given? return @solutions end self.optimize! if [:optimize] patterns = @patterns graph_name = name if graph_name.nil? @graph_name = graph_name unless graph_name.nil? # Add graph_name to pattern, if necessary unless @graph_name.nil? if patterns.empty? patterns = [Pattern.new(nil, nil, nil, graph_name: @graph_name)] else apply_graph_name(@graph_name) end end patterns.each do |pattern| old_solutions, @solutions = @solutions, Query::Solutions() bindings.each_key do |variable| if pattern.variables.include?(variable) unbound_solutions, old_solutions = old_solutions, Query::Solutions() Array(bindings[variable]).each do |binding| unbound_solutions.each do |solution| old_solutions << solution.merge(variable => binding) end end bindings.delete(variable) end end old_solutions.each do |solution| found_match = false pattern.execute(queryable, solution) do |statement| found_match = true @solutions << solution.merge(pattern.solution(statement)) end # If this pattern was optional, and we didn't find any matches, # just copy it over as-is. if !found_match && pattern.optional? @solutions << solution end end #puts "solutions after #{pattern} are #{@solutions.to_a.inspect}" # It's important to abort failed queries quickly because later patterns # that can have constraints are often broad without them. # We have no solutions at all: return @solutions if @solutions.empty? if !pattern.optional? # We have no solutions for variables we should have solutions for # (excludes non-distinguished variables): need_vars = pattern.variables.select {|k,v| v.distinguished?}.keys @solutions.each do |solution| break if need_vars.empty? need_vars -= solution.bindings.keys end return Query::Solutions() unless need_vars.empty? end end @solutions.each(&block) if block_given? @solutions end |
#failed? ⇒ Boolean
Returns true
if this query did not match when last executed.
When the solution sequence is empty, this method can be used to determine whether the query failed to match or not.
397 398 399 |
# File 'lib/rdf/query.rb', line 397 def failed? @solutions.empty? end |
#matched? ⇒ Boolean
Returns true
if this query matched when last executed.
When the solution sequence is empty, this method can be used to determine whether the query matched successfully or not.
409 410 411 |
# File 'lib/rdf/query.rb', line 409 def matched? !failed? end |
#named? ⇒ Boolean
Is this query scoped to a named graph?
422 423 424 |
# File 'lib/rdf/query.rb', line 422 def named? !!graph_name end |
#node? ⇒ Boolean Also known as: has_blank_nodes?
Returns true
if any pattern contains a blank node.
492 493 494 |
# File 'lib/rdf/query.rb', line 492 def node? patterns.any?(&:node?) || graph_name && graph_name.node? end |
#optimize(**options) ⇒ RDF::Query
Returns an optimized copy of this query.
242 243 244 |
# File 'lib/rdf/query.rb', line 242 def optimize(**) self.dup.optimize!(**) end |
#optimize!(**options) ⇒ self
Optimizes this query by reordering its constituent triple patterns according to their cost estimates.
Optional patterns have greater cost than non-optional patterns so they will always come after non-optional patterns
257 258 259 260 261 262 263 264 265 266 267 |
# File 'lib/rdf/query.rb', line 257 def optimize!(**) optional, required = @patterns.uniq.partition(&:optional?) required.sort! do |a, b| (a.cost || 0) <=> (b.cost || 0) end optional.sort! do |a, b| (a.cost || 0) <=> (b.cost || 0) end @patterns = required + optional self end |
#pattern(pattern, **options)
This method returns an undefined value.
Appends the given query pattern
to this query.
230 231 232 233 |
# File 'lib/rdf/query.rb', line 230 def pattern(pattern, **) @patterns << Pattern.from(pattern, **) self end |
#unnamed? ⇒ Boolean
Is this query unscoped? This indicates that it can return results from either a named graph or the default graph.
435 436 437 |
# File 'lib/rdf/query.rb', line 435 def unnamed? graph_name.nil? end |
#valid? ⇒ Boolean
Determine if the query containts valid patterns
538 539 540 541 542 |
# File 'lib/rdf/query.rb', line 538 def valid? !!validate! rescue raise false rescue false end |
#validate! ⇒ RDF::Query
Validate this query, making sure it can be executed by our query engine. This method is public so that it may be called by implementations of RDF::Queryable#query_execute that bypass our built-in query engine.
551 552 553 554 555 556 557 558 559 560 561 562 563 |
# File 'lib/rdf/query.rb', line 551 def validate! # All patterns must be valid @patterns.each(&:validate!) # All optional patterns must appear after the regular patterns. if i = @patterns.find_index(&:optional?) unless @patterns[i..-1].all?(&:optional?) raise ArgumentError.new("Optional patterns must appear at end of query") end end self end |
#variable? ⇒ Boolean #variable?(variables) ⇒ Boolean Also known as: variables?, has_variables?
456 457 458 459 460 461 462 463 |
# File 'lib/rdf/query.rb', line 456 def variable?(*args) case args.length when 0 then !variables.empty? when 1 patterns.any? {|p| p.variable?(*args)} else raise ArgumentError("wrong number of arguments (given #{args.length}, expected 0 or 1)") end end |
#variable_count ⇒ Integer
Returns the number of variables in this query.
483 484 485 |
# File 'lib/rdf/query.rb', line 483 def variable_count variables.keys.length end |
#variables ⇒ Hash{Symbol => RDF::Query::Variable}
The variables used in this query. This includes variables used in patterns along with the graph_name itself, if it is a variable.
471 472 473 474 475 476 477 |
# File 'lib/rdf/query.rb', line 471 def variables # Set variables used in query vars = patterns.inject({}) do |memo, pattern| memo.merge(pattern.variables) end graph_name.is_a?(Variable) ? vars.merge(graph_name.to_sym => graph_name) : vars end |