Module: Tripod::Finders::ClassMethods

Defined in:
lib/tripod/finders.rb

Instance Method Summary collapse

Instance Method Details

#_create_and_hydrate_resources_from_sparql(select_sparql, opts = {}) ⇒ Object

Given a select query, perform a DESCRIBE query to get a graph of data from which we create and hydrate a collection of resources.

Parameters:

  • options (Hash) —

    a customizable set of options



146
147
148
149
150
151
152
 
# File 'lib/tripod/finders.rb', line 146

def _create_and_hydrate_resources_from_sparql(select_sparql, opts={})
  # TODO: Optimization?: if return_graph option is false, then don't do this next line?
  uris_and_graphs = _select_uris_and_graphs(select_sparql, :uri_variable => opts[:uri_variable], :graph_variable => opts[:graph_variable])
  ntriples_string = _raw_describe_select_results(select_sparql, :uri_variable => opts[:uri_variable]) # this defaults to ntriples
  graph = _rdf_graph_from_ntriples_string(ntriples_string, graph=nil)
  _resources_from_graph(graph, uris_and_graphs)
end

#_describe_query_for_select(select_sparql, opts = {}) ⇒ Object

 For a select query, generate a query which DESCRIBES all the results

Parameters:

  • options (Hash) —

    a customizable set of options



157
158
159
160
 
# File 'lib/tripod/finders.rb', line 157

def _describe_query_for_select(select_sparql, opts={})
  uri_variable = opts[:uri_variable] || "uri"
  "DESCRIBE ?#{uri_variable} WHERE { #{select_sparql} }"
end

#_graph_of_triples_from_construct_or_describe(construct_query) ⇒ Object

given a construct or describe query, return a graph of triples.



136
137
138
139
 
# File 'lib/tripod/finders.rb', line 136

def _graph_of_triples_from_construct_or_describe(construct_query)
  ntriples_str = Tripod::SparqlClient::Query.query(construct_query, "application/n-triples")
  _rdf_graph_from_ntriples_string(ntriples_str, graph=nil)
end

#_raw_describe_select_results(select_sparql, opts = {}) ⇒ Object

For a select query, get a raw serialisation of the DESCRIPTION of the resources from the database.

Parameters:

  • options (Hash) —

    a customizable set of options



166
167
168
169
170
 
# File 'lib/tripod/finders.rb', line 166

def _raw_describe_select_results(select_sparql, opts={})
  accept_header = opts[:accept_header] || "application/n-triples"
  query = _describe_query_for_select(select_sparql, :uri_variable => opts[:uri_variable])
  Tripod::SparqlClient::Query.query(query, accept_header)
end

#_rdf_graph_from_ntriples_string(ntriples_string, graph = nil) ⇒ Object

given a string of ntriples data, populate an RDF graph. If you pass a graph in, it will add to that one.



125
126
127
128
129
130
131
132
133
 
# File 'lib/tripod/finders.rb', line 125

def _rdf_graph_from_ntriples_string(ntriples_string, graph=nil)
  graph ||= RDF::Graph.new
  RDF::Reader.for(:ntriples).new(ntriples_string) do |reader|
    reader.each_statement do |statement|
      graph << statement
    end
  end
  graph
end

#_resources_from_graph(graph, uris_and_graphs) ⇒ Object

 given a graph of data, and a hash of uris=>graphs, create and hydrate some resources. Note: if any of the graphs are not set in the hash, those resources can still be constructed, but not persisted back to DB.



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/tripod/finders.rb', line 175

def _resources_from_graph(graph, uris_and_graphs)
  repo = add_data_to_repository(graph)
  resources = []

  # TODO: ? if uris_and_graphs not passed in, we could get the
  # uris from the graph, and just not create the resoruces with a graph
  # (but they won't be persistable).

  uris_and_graphs.each_pair do |u,g|

    # instantiate a new resource
    r = self.new(u,g)

    # make a graph of data for this resource's uri
    data_graph = RDF::Graph.new
    repo.query( [RDF::URI.new(u), :predicate, :object] ) do |statement|
      data_graph << statement
    end

    # use it to hydrate this resource
    r.hydrate!(:graph => data_graph)
    r.new_record = false
    resources << r
  end

  resources
end

#_resources_from_sparql(select_sparql, opts = {}) ⇒ Object

 given a sparql select query, create and hydrate some resources

Parameters:

  • options (Hash) —

    a customizable set of options



119
120
121
 
# File 'lib/tripod/finders.rb', line 119

def _resources_from_sparql(select_sparql, opts={})
  _create_and_hydrate_resources_from_sparql(select_sparql, opts)
end

#_select_uris_and_graphs(sparql, opts = {}) ⇒ Object

based on the query passed in, build a hash of uris->graphs

Parameters:

  • sparql. (String) —

    The sparql query

  • opts. (Hash) —

    A hash of options.

  • options (Hash) —

    a customizable set of options



209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/tripod/finders.rb', line 209

def _select_uris_and_graphs(sparql, opts={})
  select_results = Tripod::SparqlClient::Query.select(sparql)

  uris_and_graphs = {}

  select_results.each do |r|
    uri_variable = opts[:uri_variable] || 'uri'
    graph_variable = opts[:graph_variable] || 'graph'
    graph_value = r[graph_variable]["value"] if r[graph_variable]
    uris_and_graphs[ r[uri_variable]["value"] ] = graph_value || nil
  end

  uris_and_graphs
end

#all ⇒ Object

 execute a query to return all objects (restricted by this class’s rdf_type if specified) returns a criteria object



77
78
79
 
# File 'lib/tripod/finders.rb', line 77

def all
  where('?uri ?p ?o')
end

#count ⇒ Object 



81
82
83
 
# File 'lib/tripod/finders.rb', line 81

def count
  self.all.count
end

#describe_select_results(select_sparql, opts = {}) ⇒ Object

returns a graph of triples which describe results of the sparql passed in.

Parameters:

  • options (Hash) —

    a customizable set of options



107
108
109
110
 
# File 'lib/tripod/finders.rb', line 107

def describe_select_results(select_sparql, opts={})
  ntriples_string = _raw_describe_select_results(select_sparql, opts) # this defaults to using n-triples
  _rdf_graph_from_ntriples_string(ntriples_string)
end

#describe_uris(uris) ⇒ Object

returns a graph of triples which describe the uris passed in.



90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/tripod/finders.rb', line 90

def describe_uris(uris)
  graph = RDF::Graph.new

  if uris.length > 0
    uris_sparql_str = uris.map{ |u| "<#{u.to_s}>" }.join(" ")

    # Do a big describe statement, and read the results into an in-memory repo
    ntriples_string = Tripod::SparqlClient::Query.query("DESCRIBE #{uris_sparql_str}", "application/n-triples")
    graph = _rdf_graph_from_ntriples_string(ntriples_string, graph)
  end

  graph
end

#find(uri, graph_uri = nil) ⇒ Resource

Find a Resource by its uri (and, optionally, by its graph if there are more than one).

Examples:

Find a single resource by a uri.

Person.find('http://ric')
Person.find(RDF::URI('http://ric'))

Find a single resource by uri and graph

Person.find('http://ric', 'http://example.com/people')
Person.find(RDF::URI('http://ric'), Person.find(RDF::URI('http://example.com/people')))

Parameters:

  • uri (String, RDF::URI) —

    The uri of the resource to find

  • graph_uri (String, RDF::URI) (defaults to: nil) —

    The uri of the graph from which to get the resource

Returns:

Raises:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/tripod/finders.rb', line 24

def find(uri, graph_uri=nil)

  unless graph_uri
    # do a quick select to see what graph to use.
    select_query = "SELECT ?g WHERE { GRAPH ?g {<#{uri.to_s}> ?p ?o } } LIMIT 1"
    result = Tripod::SparqlClient::Query.select(select_query)
    if result.length > 0
      graph_uri = result[0]["g"]["value"]
    else
      raise Tripod::Errors::ResourceNotFound.new(uri)
    end
  end

  # instantiate and hydrate the resource
  resource = self.new(uri, graph_uri.to_s)

  resource.hydrate!
  resource.new_record = false

  # check that there are triples for the resource (catches case when someone has deleted data
  # between our original check for the graph and hydrating the object.
  raise Tripod::Errors::ResourceNotFound.new(uri) if resource.repository.empty?

  # return the instantiated, hydrated resource
  resource
end

#find_by_sparql(sparql_query, opts = {}) ⇒ Array

Find a collection of Resources by a SPARQL select statement which returns their uris. Under the hood, this only executes two queries: a select, then a describe.

Examples:

Person.find_by_sparql('SELECT ?uri ?graph WHERE { GRAPH ?graph { ?uri ?p ?o } } LIMIT 3')

Parameters:

  • sparql_query. (String) —

    A sparql query which returns a list of uris of the objects.

  • opts. (Hash) —

    A hash of options.

  • options (Hash) —

    a customizable set of options

Returns:

  • (Array) —

    An array of hydrated resources of this class’s type.



64
65
66
 
# File 'lib/tripod/finders.rb', line 64

def find_by_sparql(sparql_query, opts={})
  _create_and_hydrate_resources_from_sparql(sparql_query, opts)
end

#first ⇒ Object 



85
86
87
 
# File 'lib/tripod/finders.rb', line 85

def first
  self.all.first
end

#where(sparql_snippet) ⇒ Object

 execute a where clause on this resource. returns a criteria object



70
71
72
73
 
# File 'lib/tripod/finders.rb', line 70

def where(sparql_snippet)
  criteria = Tripod::Criteria.new(self)
  criteria.where(sparql_snippet)
end