{"id":13446441,"url":"https://github.com/ANCIR/grano","last_synced_at":"2025-03-21T06:31:23.523Z","repository":{"id":10413211,"uuid":"12570700","full_name":"ANCIR/grano","owner":"ANCIR","description":"A toolkit for mapping networks of political and economic influence through diverse types of entities and their relations. Accessible at http://granoproject.org","archived":false,"fork":false,"pushed_at":"2021-03-25T21:49:12.000Z","size":3833,"stargazers_count":188,"open_issues_count":20,"forks_count":28,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-08-10T13:03:25.030Z","etag":null,"topics":["africa","ancir","code-for-africa","connected-africa","entities","grano","graph-networks","graphs","investigative-journalism","network-analysis","node-networks","python","siyazana"],"latest_commit_sha":null,"homepage":"http://granoproject.org","language":"Python","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/ANCIR.png","metadata":{"files":{"readme":"README.querylang.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":"2013-09-03T17:49:44.000Z","updated_at":"2024-05-22T21:48:44.000Z","dependencies_parsed_at":"2022-08-29T15:41:51.903Z","dependency_job_id":null,"html_url":"https://github.com/ANCIR/grano","commit_stats":null,"previous_names":["codeforafrica/grano"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANCIR%2Fgrano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANCIR%2Fgrano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANCIR%2Fgrano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ANCIR%2Fgrano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ANCIR","download_url":"https://codeload.github.com/ANCIR/grano/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244750757,"owners_count":20504136,"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":["africa","ancir","code-for-africa","connected-africa","entities","grano","graph-networks","graphs","investigative-journalism","network-analysis","node-networks","python","siyazana"],"created_at":"2024-07-31T05:00:53.204Z","updated_at":"2025-03-21T06:31:23.113Z","avatar_url":"https://github.com/ANCIR.png","language":"Python","funding_links":[],"categories":["Python","python"],"sub_categories":[],"readme":"# Grano Query Language\n\nThis repository contains an experimental query language implementation for grano. It is\nintended to augment the existing REST API with a more advanced way of accessing data.\n\nGrano QL is inspired by MQL, the [Metaweb Query Language](http://wiki.freebase.com/wiki/MQL)\nused to query Freebase. Its query-by-example approach seems more appropriate for a web\ninterface than SQL-inspired query languages such as Neo4J's [CYPHER](http://docs.neo4j.org/chunked/stable/cypher-query-lang.html)\nor RDF's [SPARQL](http://www.w3.org/TR/rdf-sparql-query/).\n\n* [MQL language reference](http://mql.freebaseapps.com/ch03.html)\n* [MQL operators](http://wiki.freebase.com/wiki/MQL_operators)\n\n**WARNING**: At this moment, the plugin does not implement authorization\nchecks. When enabled, it will make all data in your grano instance\naccessible, regardless of permissions.\n\n\n## Comments and Feedback\n\nThis document and the implementation in this repository are requests for\ncomments - none of the features are fixed at this point; and any\nconcerns by users are valuable feedback, even if they imply significant\nchanges to the language. \n\n\n## Submitting queries\n\nWhen installed the Grano QL API endpoint is available at:\n\n      /api/1/query\n\nQueries can be submitted via HTTP GET or POST request. For GET requests, a JSON string is expected to be submitted in the ``query`` query string argument. POST requests are expected to carry the payload as the body, using ``application/json`` as a content type.\n\n\n## Basic queries\n\nA simple query could look like this:\n\n    {\n      \"properties\": {\n        \"name\": \"Barack Obama\"\n      },\n      \"id\": null\n    }\n\nWhich means: *get the id of the entity with the name Barack Obama.* \n\nAll grano QL queries run against entities, although we'll see below how\nthey can be used to retrieve relations.\n\nAs seen above, submitting ``null`` for any field will attempt to retrieve\nit. As a shortcut, a default set of fields can be retrieved using a\nwildcard:\n\n    {\n      \"*\": null\n    }\n\nSimilarly, a filter can be set by submitting a value for a given field:\n\n    {\n      \"id\": \"xxx\",\n      \"*\": null\n    }\n\nThis will retrieve the default set of fields for the entity with the\nspecified ``id``.\n\n\n### Lists vs. object retrieval\n\nTo further specify the desired return type, empty lists can be used to signify\nwhether the query should return a single item or a list of items:\n\n    {\n      \"schemata\": {} // get the first available item\n      // vs.\n      \"schemata\": [{}] // get all available items\n    }\n\nThis also applies to the root of the query object: queries can either\naim to retrieve one or many entities. This will get all entities\n(pagination is used):\n\n    [{\n      \"*\": null\n    }]\n\n\n## Available fields\n\nBased on these simple entity queries, the grano graph can be traversed.\nThe following fields are available:\n\n* ``id``, ``status``, ``created_at``, ``updated_at`` as simple fields on\n  entities.\n* ``author`` is an account, with these properties:\n  * ``login`` the login name\n  * ``full_name``, ``id``, ``created_at``, ``updated_at``\n* ``project`` the associated project, with these properties:\n  * ``slug``, ``label``, ``id``, ``created_at``, ``updated_at``\n* ``schemata`` a set of schemata, each with these properties:\n  * ``name``, ``label``, ``hidden``, ``created_at``, ``updated_at``\n* ``properties`` can have a set of properties defined as nested objects,\n  with these properties on each:\n  * ``name``, ``value``, ``source_url``, ``active``\n* ``inbound`` has a list of inbound relations. Each relation has these\n  fields: \n  * ``id``, ``created_at``, ``updated_at``\n  * ``schema``, ``author`` and ``project``, analogous to those on entities.\n  * ``source`` is an entity, with all it's properties available.\n* ``outbound``, a list of outbound relations. Same as ``inbound``,\n  except with a ``target`` entity instead of ``source``.\n\nSome of the nested objects can be abbreviated when filtering, e.g. you\ncan filter for ``{\"project\": \"test\"}`` instead of ``{\"project\": {\"slug\":\n\"test\"}}``. This applies to schemata names, author logins and property\nvalues.\n\n## Discussion\n\nWhat's cool about this type of query:\n\n* Readable JSON, easily constructed by a web frontend application. \n* Resembles the representation in the REST API; query and result are basically the same thing.\n* Granular access to individual properties, or constellations of objects.\n\nPotential Problems:\n\n* How do we tell the difference between null as in \"return this value\" and null as in \"this property is null\"?\n\n\n## Indexes\n\nCREATE INDEX dbg1 ON grano_entity (project_id);\nCREATE INDEX dbg2 ON grano_entity_schema (entity_id);\nCREATE INDEX dbg3 ON grano_entity (id);\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FANCIR%2Fgrano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FANCIR%2Fgrano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FANCIR%2Fgrano/lists"}