Sparqlight

Sparqlight is a blacklight application; it replaces the Solr index documents with SPARQL results from graph queries.

Configuration changes

Database

Sparqlight changes the database configuration, replacing Solr with a SPARQL endpoint, e.g.

# config/blacklight.yml

development:
  adapter: Sparql
  url: <%= ENV['SPARQL_URL'] %>
  repository: "mongo"
  collection: "nomisma_full"
test: &test
  adapter: Sparql
  repository: "mongo"
  collection: "nomisma"
production:
  adapter: Sparql
  url: <%= ENV['SPARQL_URL'] || "http://127.0.0.1/FIXME" %>

Routes

Sparqlite replaces a :solr_documents with a :sparql_documents resource:

  resources :sparql_documents, only: [:show], path: '/catalog', controller: 'catalog' do
    concerns :exportable
  end
  #resources :solr_documents, only: [:show], path: '/catalog', controller: 'catalog' do
  #  concerns :exportable
  #end

Catalog Controller

Sparqlight changes the default blacklight configuration, including:

# app/controllers/catalog_controller.rb
configure_blacklight do |config|

  # Class for sending and receiving requests from a search index
  # sparqlite removes: config.repository_class = Blacklight::Solr::Repository
  config.repository_class = Blacklight::Sparql::Repository

  # Model that describes a Document
  config.document_model = ::SparqlDocument

  # Model that maps search index responses to the blacklight response model
  # sparqlite removes: config.response_model = Blacklight::Solr::Response
  config.response_model = Blacklight::Sparql::Response

  # Sparqlite removes:
  # Default parameters to send to solr for all search-like requests....
  # config.default_solr_params = { ... }

  # etc.
end

Sparqlite adds SPARQL prefixes and jsonld contexts, e.g.

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  # Prefix definition for SPARQL queries
  config.sparql_prefixes = {
    skos: "http://www.w3.org/2004/02/skos/core#",
    dcterms: "http://purl.org/dc/terms/",
    # etc.
  }

  config.entity_class = "nmo:Denomination"

  # JSON-LD frame used for generating response documents
  config.frame = JSON.parse %({
    "@context": {
      "nmo": "http://nomisma.org/ontology#",
      "skos": "http://www.w3.org/2004/02/skos/core#",
      "dcterms": "http://purl.org/dc/terms/",
      "skos:prefLabel": {"@language": "en"},
      "skos:definition": {"@language": "en"}
    },
    "@type": "nmo:Denomination",
    "dcterms:isPartOf": {
      "@type": "nmo:FieldOfNumismatics"
    }
  })

  # etc.
end

Facet Fields

Sparqlite modifies the configuration for facet fields.

Facet fields, may be bound when querying

• field name is predicate or other distinguishing identifier
• label used for human-readible form label
• variable is the SPARQL variable associated with the field
• patterns (optional) are SPARQL triple patterns necessary to navigate between ?id and variable. Defaults to a pattern composed of ?id, predicate and variable.
• predicate defaults to field name, but may be set separately if multiple fields use the same predicate (i.e., in different entities)
• filter_language set to true, if the configured language should be used as a filter for the variable result if it is a language-tagged literal.

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  config.add_facet_field 'num_label',
    label: 'Numismatics',
    variable: "?num_lab",
    patterns: [
      "?id dcterms:isPartOf ?num",
      "?num a nmo:FieldOfNumismatics",
      "?num skos:prefLabel ?num_lab"
    ],
    filter_language: true
  
  #etc.
end

Index Fields

Sparqlite modifies the configuration for index fields.

Sparql fields to be displayed in the index (search results) view. The ordering of the field names is the order of the display.

• field name is predicate or other distinguishing identifier
• variable is the SPARQL variable associated with the field
• predicate defaults to field name, but may be set separately if multiple fields use the same predicate (i.e., in different entities)
• patterns (optional) are SPARQL triple patterns necessary to navigate between ?id and variable. They default to using the field name as the predicate relating ?id and variable. These are also used in CONSTRUCT when generating RDF triples to frame.
• filter_language set to true, if the configured language should be used as a filter for the variable result if it is a language-tagged literal.

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  # Sparql fields to be displayed in the index (search results) view.
  # The ordering of the field names is the order of the display.
  config.add_index_field 'skos:prefLabel', label: 'Label', variable: "?lab", filter_language: true
  config.add_index_field 'skos:definition', label: 'Definition', variable: "?defn", filter_language: true
  config.add_index_field 'num_label',
    field: 'dcterms:isPartOf',
    helper_method: 'render_numismatics',
    label: 'Numismatics',
    variable: "?num_lab",
    patterns: [
      "?id dcterms:isPartOf ?num",
      "?num a nmo:FieldOfNumismatics",
      "?num skos:prefLabel ?num_lab"
    ],
    filter_language: true

  # etc.
end

Show Fields

Sparqlite modifies the configuration for show fields:

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  # Sparql fields to be displayed in the show (single result) view
  #   The ordering of the field names is the order of the display 
  config.add_show_field 'skos:prefLabel', label: 'Label', variable: "?lab", filter_language: true
  config.add_show_field 'skos:definition', label: 'Definition', variable: "?defn", filter_language: true
  config.add_show_field 'num_label',
    field: 'dcterms:isPartOf',
    helper_method: 'render_numismatics',
    label: 'Numismatics',
    variable: "?num_lab",
    patterns: [
      "?id dcterms:isPartOf ?num",
      "?num a nmo:FieldOfNumismatics",
      "?num skos:prefLabel ?num_lab"
    ],
    filter_language: true

  # etc.
end

Search Fields

Sparqlite modifies the configuration for search fields.

Sparqlite adds a CONTAINS filter on the specified variable.

• field name is predicate or other distinguishing identifier
• variable is one or more SPARQL variables associated with the fields to search
• patterns (optional) are SPARQL triple patterns necessary to filter for matching triples.
• predicate defaults to field name, but may be set separately if multiple fields use the same predicate (i.e., in different entities)
• patterns (optional) are SPARQL triple patterns necessary filter results based on the search term. Defaults to "FILTER(CONTAINS(%{variable}, '%{term}'))", there %{lab_term} is substituted in the. where multiple variables are CONCATenated

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  # "fielded" search configuration. Used by pulldown among other places.
  # For supported keys in hash, see rdoc for Blacklight::SearchFields
  config.add_search_field('all_fields') do |field|
    field.label = 'All Fields'
    field.default = true
    field.variable = %w(?lab ?defn ?num_lab)
    field.patterns = ["FILTER(CONTAINS(STR(CONCAT(?lab, ?defn, ?num_lab)), '%{q}'))"]
  end
 
  config.add_search_field('label') do |field|
    field.label = 'Label'
    field.variable = "?lab"
    field.patterns = ["FILTER(CONTAINS(STR(?lab), '%{q}'))"]
  end

  # etc.
end

Sort Fields

# app/controllers/catalog_controller.rb
configure_blacklight do |config|
  # etc.

  # "sort results by" select (pulldown)
  # label in pulldown is followed by the name of the SPARQL variable to sort by and
  # whether the sort is ascending or descending (it must be asc or desc
  # except in the relevancy case).
  config.add_sort_field '?lab asc', label: 'Label'
  config.add_sort_field '?defn asc', label: 'Definition'

  # etc.
end