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.
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 |
# File 'lib/rdf/query.rb', line 183 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
413 414 415 |
# File 'lib/rdf/query.rb', line 413 def +(other) Query.new(self.patterns + other.patterns) end |
#<<(pattern)
This method returns an undefined value.
Appends the given query pattern
to this query.
213 214 215 216 |
# File 'lib/rdf/query.rb', line 213 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
438 439 440 441 |
# File 'lib/rdf/query.rb', line 438 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?
425 426 427 |
# File 'lib/rdf/query.rb', line 425 def default? graph_name == false end |
#dup ⇒ RDF::Query
Duplicate query, including patterns and solutions
525 526 527 528 |
# File 'lib/rdf/query.rb', line 525 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.
506 507 508 |
# File 'lib/rdf/query.rb', line 506 def each_solution(&block) @solutions.each(&block) end |
#each_statement {|RDF::Query::Pattern| ... } ⇒ Enumerator
Enumerates over each statement (pattern).
517 518 519 520 |
# File 'lib/rdf/query.rb', line 517 def each_statement(&block) apply_graph_name patterns.each(&block) end |
#empty? ⇒ Boolean
Query has no patterns
495 496 497 |
# File 'lib/rdf/query.rb', line 495 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.
308 309 310 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 |
# File 'lib/rdf/query.rb', line 308 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.
394 395 396 |
# File 'lib/rdf/query.rb', line 394 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.
406 407 408 |
# File 'lib/rdf/query.rb', line 406 def matched? !failed? end |
#named? ⇒ Boolean
Is this query scoped to a named graph?
419 420 421 |
# File 'lib/rdf/query.rb', line 419 def named? !!graph_name end |
#node? ⇒ Boolean Also known as: has_blank_nodes?
Returns true
if any pattern contains a blank node.
489 490 491 |
# File 'lib/rdf/query.rb', line 489 def node? patterns.any?(&:node?) || graph_name && graph_name.node? end |
#optimize(**options) ⇒ RDF::Query
Returns an optimized copy of this query.
240 241 242 |
# File 'lib/rdf/query.rb', line 240 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
255 256 257 258 259 260 261 262 263 264 265 |
# File 'lib/rdf/query.rb', line 255 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.
228 229 230 231 |
# File 'lib/rdf/query.rb', line 228 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.
432 433 434 |
# File 'lib/rdf/query.rb', line 432 def unnamed? graph_name.nil? end |
#valid? ⇒ Boolean
Determine if the query containts valid patterns
535 536 537 538 539 |
# File 'lib/rdf/query.rb', line 535 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.
548 549 550 551 552 553 554 555 556 557 558 559 560 |
# File 'lib/rdf/query.rb', line 548 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?
453 454 455 456 457 458 459 460 |
# File 'lib/rdf/query.rb', line 453 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.
480 481 482 |
# File 'lib/rdf/query.rb', line 480 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.
468 469 470 471 472 473 474 |
# File 'lib/rdf/query.rb', line 468 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 |