{"id":16718662,"url":"https://github.com/planeshifter/node-sparqling-star","last_synced_at":"2025-04-10T08:53:57.914Z","repository":{"id":19206897,"uuid":"22440571","full_name":"Planeshifter/node-sparqling-star","owner":"Planeshifter","description":"node.js client for creating SPARQL queries and communicating with services like DBpedia","archived":false,"fork":false,"pushed_at":"2016-02-16T18:48:58.000Z","size":66,"stargazers_count":8,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T08:08:39.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Planeshifter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-30T18:50:04.000Z","updated_at":"2016-11-08T02:09:05.000Z","dependencies_parsed_at":"2022-08-24T13:54:05.641Z","dependency_job_id":null,"html_url":"https://github.com/Planeshifter/node-sparqling-star","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Planeshifter%2Fnode-sparqling-star","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Planeshifter%2Fnode-sparqling-star/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Planeshifter%2Fnode-sparqling-star/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Planeshifter%2Fnode-sparqling-star/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Planeshifter","download_url":"https://codeload.github.com/Planeshifter/node-sparqling-star/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248190407,"owners_count":21062277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T21:38:01.086Z","updated_at":"2025-04-10T08:53:57.883Z","avatar_url":"https://github.com/Planeshifter.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM version][npm-image]][npm-url]\n[![Build Status][travis-image]][travis-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[![Dependencies][dependencies-image]][dependencies-url]\n\nSPARQLing Star\n===================\n\n\u003e node.js client for creating [SPARQL][sparql] queries and communicating with services like [DBpedia][dbpedia]\n\n# Introduction\n\nThis package allows you to create [SPARQL][sparql] calls via JavaScript object notation and to query a [SPARQL][sparql] endpoint and fetch the results.\n\n## What it is about?\n\nUsing the query language [SPARQL][sparql] (Simple Protocol and RDF Query Language), this module provides facilities to retrieve machine-readable data stored in RDF. RDF stands for Resource Description Framework and is a way to store data in triplets, following the syntactical structure of subject, predicate and noun. In a very practical sense, it gives an access point to semantic web technologies and databases. One of the prime examples is the [DBpedia][dbpedia], which is the machine-readable form of [Wikipedia][wikipedia]. [DBpedia][dbpedia] allows you to understand the [Wikipedia][wikipedia] as a big, structured database from which valuable information can be extracted.  \n\n# Getting Started\n\nTo install the package, call\n\n```\nnpm install sparqling-star\n```\n\nfrom your working directory. To require the package in a *.js file, use the usual syntax:\n\n```javascript\nvar sparqler = require( 'sparqling-star' );\n```\n\nIf you are interested in using the package not only on the server, but also client-side, you could use [Browserify][browserify] to convert your code into one single *.js file which can easily be embedded in an HTML document.\n\n## Quick Overview\n\nTo give you an idea on how the package works, we are going through the steps of creating a call to [DBpedia][dbpedia] and printing the fetched results to the console. Our objective is to load all the names of the music albums from Eminem. After loading the package, we can construct a query object as follows:\n\n```javascript\nvar myquery = new sparqls.Query();\n```\n\nThis is an empty query object, so we have to add some information. Our *myquery* object expects JavaScript objects to perform the search. First, we create an *album* object which specifies the properties that we wish to retrieve.\n\n```javascript\nvar album = {\n\t'type': 'dbo:Album',\n\t'dbo:artist' : 'dbr:Eminem'\n};\n```\n\nIn this object, the keys represent the RDF predicates and the right-hand side our search values.\n\nThen we have to register the query object in our query:\n\n```javascript\nmyquery.registerVariable( 'album', album );\n```\n\nBehind the scenes, this creates a valid [SPARQL][sparql] call. To retrieve the code, you can access the *sparqlQuery* property of the *myquery* object as in `myquery.sparqlQuery`, which will print out\n\n```\nSELECT * WHERE {\n\t?album a dbo:Album .\n\t?album dbo:artist dbr:Eminem .\n}\nLIMIT 100\n```\n\nTo test the created code, you can use a web frontend of a SPARQL endpoint of [DBpedia][dbpedia] such as [Virtuoso](http://dbpedia.org/sparql).\n\nTo fetch results in JSON format inside of JavaScript, we have to create a client object that communicates with a [SPARQL][sparql] endpoint. The constructor function Client has an optional string parameter to specify the endpoint. If you do not pass an argument when calling the function, it will default to *http://dbpedia.org/sparql*. Since we are fine with this in our current application, we can simply type\n\n```javascript\nvar sparqler = new sparqls.Client();\n```\n\nWith this object, you can send a multitude of queries, even at the same time. One simply has to pass a Query object to the send method and provide as a second argument a callback function which has two parameters: `error` and `data`.\n\n```javascript\nsparqler.send( myquery, function( error, data ) {\n\tconsole.log( data.results.bindings );\n});\n```\n\nBy default, a created [SPARQL][sparql] call will fetch all variables that have been registered. [DBpedia][dbpedia] provides a nice visual interface which gives you a preview of all the information stored for a certain entity. The URL for the [DBpedia][dbpedia] entry for Eminems second album, the Marshall Mathers LP, is [http://dbpedia.org/page/The_Marshall_Mathers_LP](http://dbpedia.org/page/The_Marshall_Mathers_LP). For example, we could extend our album object to also include the music genre and the record label:\n\n```javascript\nvar extendedAlbum = {\n\t'type': 'dbo:Album',\n\t'dbo:artist': 'dbr:Eminem',\n\t'dbo:genre': '?genre',\n\t'dbo:recordLabel': '?recordLabel'\n};\n```\n\nAs you can see here, this query differs from the previous one insofar as it introduces open variables that we want to retrieve but upon which we do not impose any restrictions. We use a starting \"?\" for such local variables. Using a new query, we can retrieve the results as follows:\n\n```javascript\nvar myquery2 = new sparqls.Query();\nmyquery2.registerVariable( 'extendedAlbum', extendedAlbum );\n\nsparqler.send( myquery2, function( error, data ) {\n\tconsole.log( util.inspect( data.results.bindings ) );\n});\n```\n\n# Further Options\n\n## Selection\n\nBy default, all registered and other variables are returned in the result set. This corresponds to a \"SELECT *\" statement in [SPARQL][sparql]. However, you might want to reduce the returned data by specifying the result set explicitly. This is achieved by using the `selection` method of the query object. Assume that we only want to view the record labels of Eminems albums. We can do this by typing\n\n```javascript\nmyquery2.selection( 'recordLabel' );\n```\n\nBesides passing a string, it is also possible to supply a multitude of variables arranged in a JavaScript Array. As you may notice, the returned result set contains multiple instances of the different record labels. To only retrieve these instances once, we can use a modifier.\n\n## Modifiers\n\n### Distinct\n\nWhen creating a query, we can use the *distinct* option to filter out duplicate instances. All modifiers are set when creating the query object.\n\n```javascript\nvar myquery3 = new sparqls.Query({\n    'distinct': true\n});\n```\n\n### Reduced\n\nWhile the distinct modifier ensures that duplicates are eliminated from the result set, reduced just allows them to be eliminated.\n\n```javascript\nvar myquery3 = new sparqls.Query({\n    'reduced': true\n});\n```\n\n### Limit\n\nTo limit the size of the result set, we use the limit modifier.\n\n```javascript\nvar myquery3 = new sparqls.Query({\n    'limit': 5\n});\n```\n\nBy default, a maximum of a hundred entries is returned.\n\n### Offset\n\nTo skip say the first five results, you can define an offset:\n\n```javascript\nvar myquery3 = new sparqls.Query({\n    'offset': 5\n});\n```\n\nYou can also combine these modifiers, e.g. as in\n\n```javascript\nvar myquery3 = new sparqls.Query({\n\t'offset': 5,\n\t'limit': 20,\n\t'reduced': true,\n\t'distinct': false\n});\n```\n\n## Order By\n\nThe query object might be ordered by passing a regular SPARQL command to its order method.\n\n```javascript\nmyquery3.order( 'ASC(?extendedAlbum)' );\n```\n\n## Filters\n\nTo refine your query, you can use filters. These again accept valid [SPARQL][sparql] filter expressions. For example, we could only retain results in which the city contains \"New\".\n\n```javascript\nmyquery.filter( 'regex(?city, \\'New\\')' );\n```\n\n## Prefixes\n\nPrefixes can be created as follows:\n\n```javascript\nmyquery.registerPrefix( 'dbres', '\u003chttp://dbpedia.org/resource/\u003e' );\n```\n\nThis important if you wish to combine ontologies and query other endpoints besides [DBpedia][dbpedia].\n\n\n## Custom Triples\n\nTo create custom triples in which the *subject* is not equal to a query variable, use the `registerTriple` function, which expects an object with three keys `subject`, `predicate` and `objects`, all of which have to be strings.\n\n```javascript\nvar customQuery = new sparqls.Query();\nvar triple = {\n\t'subject': '\u003chttp://dbpedia.org/resource/Civil_engineering\u003e',\n\t'predicate': 'dct:subject',\n\t'object': '?abstract'\n};\ncustomQuery.registerTriple( triple );\n```\n\n## Method Chaining\n\nOne of the neat features of the SPARQLing star package is that it allows method chaining, that is you can build up your query in one rush like this:\n\n```javascript\nmyquery\n\t.registerVariable( 'company', company )\n\t.registerVariable( 'city', city )\n\t.registerPrefix( 'dbres', '\u003chttp://dbpedia.org/resource/\u003e' )\n\t.selection( [ 'company', 'num' ] )\n\t.order( 'ASC(?num)' );\n```\n\nThis sample code is taken from the *companies.js* file. You can find all example code in the *examples* subdirectory of this repository.\n\n\n## License\n\nMIT © [Philipp Burckhardt](http://www.philipp-burckhardt.com), 2014-2016\n\n[npm-url]: https://npmjs.org/package/sparqling-star\n[npm-image]: https://badge.fury.io/js/sparqling-star.svg\n\n[travis-url]: https://travis-ci.org/Planeshifter/node-sparqling-star\n[travis-image]: https://travis-ci.org/Planeshifter/node-sparqling-star.svg?branch=master\n\n[coveralls-image]: https://img.shields.io/coveralls/Planeshifter/node-sparqling-star/master.svg\n[coveralls-url]: https://coveralls.io/r/Planeshifter/node-sparqling-star?branch=master\n\n[dependencies-image]: https://david-dm.org/Planeshifter/node-sparqling-star.svg?theme=shields.io\n[dependencies-url]: https://david-dm.org/Planeshifter/node-sparqling-star\n\n[wikipedia]: https://en.wikipedia.org/wiki/Main_Page\n[dbpedia]: http://wiki.dbpedia.org/\n[sparql]: https://en.wikipedia.org/wiki/SPARQL\n[browserify]: http://browserify.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaneshifter%2Fnode-sparqling-star","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplaneshifter%2Fnode-sparqling-star","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplaneshifter%2Fnode-sparqling-star/lists"}