{"id":15634663,"url":"https://github.com/capjamesg/knowledge-graph-language","last_synced_at":"2025-04-10T04:36:18.802Z","repository":{"id":228861369,"uuid":"775121410","full_name":"capjamesg/knowledge-graph-language","owner":"capjamesg","description":"A query language for exploring knowledge graphs.","archived":false,"fork":false,"pushed_at":"2024-08-16T21:52:39.000Z","size":78,"stargazers_count":142,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-06T06:11:31.371Z","etag":null,"topics":["knowledge-graph","programming-language"],"latest_commit_sha":null,"homepage":"https://jamesg.blog/kgl/","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/capjamesg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-20T19:55:30.000Z","updated_at":"2025-03-20T14:00:26.000Z","dependencies_parsed_at":"2024-04-08T15:45:54.825Z","dependency_job_id":"6cf58b64-d4d9-49d0-8578-8ab3ad95cb59","html_url":"https://github.com/capjamesg/knowledge-graph-language","commit_stats":null,"previous_names":["capjamesg/knowledge-graph-language"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capjamesg%2Fknowledge-graph-language","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capjamesg%2Fknowledge-graph-language/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capjamesg%2Fknowledge-graph-language/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capjamesg%2Fknowledge-graph-language/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capjamesg","download_url":"https://codeload.github.com/capjamesg/knowledge-graph-language/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248158860,"owners_count":21057216,"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":["knowledge-graph","programming-language"],"created_at":"2024-10-03T10:55:35.584Z","updated_at":"2025-04-10T04:36:18.781Z","avatar_url":"https://github.com/capjamesg.png","language":"Python","readme":"[![DOI](https://zenodo.org/badge/775121410.svg)](https://zenodo.org/doi/10.5281/zenodo.10884108)\n[![version](https://badge.fury.io/py/kgl.svg)](https://badge.fury.io/py/kgl)\n[![license](https://img.shields.io/pypi/l/kgl)](https://github.com/capjamesg/knowledge-graph-language/blob/main/LICENSE.md)\n[![python-version](https://img.shields.io/pypi/pyversions/kgl)](https://badge.fury.io/py/kgl)\n[![test workflow](https://github.com/capjamesg/knowledge-graph-language/actions/workflows/tests.yml/badge.svg)](https://github.com/capjamesg/knowledge-graph-language/actions/workflows/tests.yml)\n\n# Knowledge Graph Language (KGL)\n\nKnowledge Graph Language is a query language for interacting with graphs. It accepts semantic triples (i.e. `(\"James\", \"Enjoys\", \"Coffee\")`), indexes them, and makes them available for querying.\n\nHere is a demo of the language in action:\n\nhttps://github.com/capjamesg/knowledge-graph-language/assets/37276661/1db1683e-94a0-46bc-9292-3aa28ffc8e72\n\nYou can use this language to:\n\n- Find all attributes associated with a node in a graph.\n- Return all nodes that are connected to a node.\n- Return all nodes that are connected to a node and meet a specified condition.\n- Find how two nodes connect in a graph.\n\nThis README serves as the official language reference.\n\nThe following blog posts discuss the design of the KGL language and the interpreter, respectively:\n\n- [Designing a knowledge graph query language](https://jamesg.blog/2024/03/22/kgl/)\n- [Designing an interpreter for Knowledge Graph Language (KGL)](https://jamesg.blog/2024/03/25/kgl-interpreter/)\n\nYou can [try the language](https://jamesg.blog/kgl) on a knowledge graph calculated from James' Coffee Blog.\n\n## Syntax\n\n### Cheat Sheet\n\n```\n{ coffee } # Query a single item\n\n{ coffee -\u003e is } # Query a relationship of an item\n\n{ coffee -\u003e is }! # Show all second degree connections to the results from the query { coffee -\u003e is }\n\n{ coffee }? # Query if { coffee } returns a value\n\n{ coffee }# # State the number of edges attached to the node\n\n{ coffee } \u003c-\u003e { taylor swift } # Find the shortest connecting path between \"coffee\" and \"taylor swift\"\n\n{ coffee -\u003e isMadeBy (\"Company\" = \"Hasbean\") } # Find all coffees made by the company Hasbean\n\n{ folklore } + { evermore } # Combine the results of two queries\n\n{ taylorSwift | folklore } # Query the \"folklore\" node in the \"taylorSwift\" graph (the default graph is called \"default\" and is implicit)\n```\n\n\n### Query a Single Item\n\nYou can query a single item:\n\n```\n{ James }\n```\n\nThis will return all items associated with the `James` entry:\n\n```python\n{'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Making coffee']}\n```\n\n### Sequential Queries\n\nThe Knowledge Graph Language flows from left to right. You can make a statement, then use an arrow (`-\u003e`) to query an attribute related to the result:\n\nConsider the following query:\n\n```\n{ James -\u003e WorksFor -\u003e Makes }\n```\n\nThis query gets the `James` item, retrieves for whom James works, then reports the `Makes` attribute for the employer.\n\nThe query returns:\n\n```python\n['Computer vision software.']\n```\n\n### Filter Queries\n\n\u003e [!IMPORTANT]  \n\u003e This feature is not fully implemented.\n\nYou can filter queries so that the flow of data is constrained to only work with results that match a condition.\n\nConsider this query:\n\n```\n{ Roboflow -\u003e WorksFor (\"Enjoys\" = \"Coffee\") -\u003e Hobbies }\n```\n\nThis query gets the `Roboflow` node. Then, the query gets everyone who works at Roboflow who enjoys coffee. The query then finds who everyone works for, and returns their hobbies.\n\nThis returns:\n\n```python\n['Making coffee']\n```\n\nYou can filter by the number of items connected to a node in the graph, too.\n\nConsider these triples:\n\n```\n(\"CLIP\", \"isA\", \"Paper\")\n(\"CLIP\", \"Authors\", \"Person 1\")\n(\"CLIP\", \"Authors\", \"Person 2\")\n(\"Person 1\", \"Citations\", \"Paper 42\")\n(\"Person 2\", \"Citations\", \"Paper 1\")\n(\"Person 2\", \"Citations\", \"Paper 2\")\n(\"Person 2\", \"Citations\", \"Paper 3\")\n(\"Person 2\", \"Citations\", \"Paper 4\")\n```\n\n\nSuppose you want to find all authors of the CLIP paper in a research graph, but you only want to retrieve authors whose work has been cited at least three times. You can do this with the following query:\n\n```\n{ CLIP -\u003e Authors (\"Citations\" \u003e \"3\") }\n```\n\nThis query returns:\n\n```python\n['Person 2']\n```\n\nThis is because only `Person 2` has greater than three citations to their works.\n\n### Describe Relationships\n\nSuppose you want to know how `James` and `Roboflow` relate. For this, you can use the interrelation query operator (`\u003c-\u003e`).\n\nConsider this query:\n\n```\n{ Roboflow \u003c-\u003e James }\n```\n\nThis returns:\n\n```python\n['Roboflow', ('James', 'WorksFor')]\n```\n\nSerialized into Knowledge Graph Language, this response is represented as:\n\n```\nRoboflow -\u003e WorksFor\n```\n\nIf we execute that query in introspection mode, we can see all information about James:\n\n```\n{ Roboflow -\u003e WorksFor }!\n```\n\nThis returns:\n\n```python\n[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]\n```\n\n### Introspection\n\nBy default, all Sequential Queries return single values. For example, this query returns the names of everyone who works at Roboflow:\n\n```\n{ Roboflow -\u003e WorksFor }\n```\n\nThe response is:\n\n```python\n['James', 'Lenny']\n```\n\nWe can enable introspection mode to learn more about each of these responses. To enable introspection mode, append a `!` to the end of your query:\n\n```\n{ Roboflow -\u003e WorksFor }!\n```\n\nThis returns all attributes related, within one degree, to James and Lenny, who both work at Roboflow:\n\n```python\n[{'James': {'Birthday': ['March 20th, 2024'], 'WorksFor': ['Roboflow', 'PersonalWeb', 'IndieWeb'], 'Enjoys': ['Coffee'], 'Hobbies': ['Coffee']}}, {'Lenny': {'WorksFor': ['MetaAI', 'Roboflow']}}]\n```\n\n### Description Operators\n\nBy default, Knowledge Graph Language returns the value associated with your query. You can add operators to the end of your query to change the output.\n\nYou can use:\n\n- `?` to return True if your query returns a response and False if your query returns no response.\n- `#` to count the number of responses\n- `!` to return an introspection response.\n\n## Data Format\n\nThis project allows you to index triples of data like:\n\n```python\n(\"James\", \"Enjoys\", \"Coffee\")\n(\"James\", \"Hobbies\", \"Making coffee\")\n(\"James\", \"WorksFor\", \"Roboflow\")\n(\"Roboflow\", \"Makes\", \"Computer Vision\")\n(\"Roboflow\", \"EntityType\", \"Company\")\n```\n\nA graph is then constructed from the triples that you can then query.\n  \n## Python API\n\nFirst, install KGL:\n\n```\npip install kgl\n```\n\n### Create a Knowledge Graph\n\n```python\nfrom kgl import KnowledgeGraph\n\nkg = KnowledgeGraph()\n```\n\n### Ingest Items\n\nYou can ingest triples of strings:\n\n```python\nkg.add_node((\"Lenny\", \"Owns\", \"Roboflow\"))\n```\n\nYou can also ingest triples whose third item is a list:\n\n```python\nkg.add_node((\"Alex\", \"Citations\", [\"MetaAI\", \"GoogleAI\", \"Coffee\", \"Teacup\", \"Roboflow\"]))\n```\n\n#### Add Data in Native KGL\n\nYou can add a relation in native KGL using the following syntax:\n\n```\n{ subject, predicate, object }\n```\n\nHere is an example:\n\n```\n{ Lenny, Owns, Roboflow }\n```\n\n#### Ingest from CSV\n\nTo load data from a CSV file, use:\n\n```python\nkg = KnowledgeGraph().load_from_csv(\"./file.csv\")\n```\n\nEach line in the CSV file should use the structure:\n\n```\nsubject, predicate, object\n```\n\nThere should be no header row in your file.\n\n#### Ingest from TSV\n\nTo load data from a TSV file, use:\n\n```python\nkg = KnowledgeGraph().load_from_tsv(\"./file.tsv\")\n```\n\nEach line in the TSV file should use the structure:\n\n```\nsubject  predicate  object\n```\n\nThere should be no header row in your file.\n\n#### Ingest from JSON\n\nTo load data from a JSON file, use:\n\n```python\nkg = KnowledgeGraph().load_from_json_file(\"./file.json\")\n```\n\nThe JSON file should have the structure:\n\n```json\n[\n  {\n    \"Entity\": \"Tessa Violet\",\n    \"is\": \"a singer\",\n    \"wrote\": [\"Games\", \"Haze\"]\n  }\n]\n```\n\n`Entity` is a reserved key (case sensitive) that states the entity to which all pairs in a specific JSON entry.\n\nThis will be converted into the triples:\n\n```python\n(\"Tessa Violet\", \"is\", \"a singer\")\n(\"Tessa Violet\", \"wrote\", [\"Games\", \"Haze\"]\n```\n\nThese triples will then be ingested into a KGL data store.\n\n### Evaluate a Query\n\n```python\nresult, query_time = kg.evaluate(\"{ James }\")\nprint(result)\nprint(query_time)\n```\n\nResponses are valid Python objects, whose type varies depending on your query.\n\nBy default, KGL returns a list.\n\nBut:\n\n- `!` queries return dictionaries.\n- `#` queries return integers.\n- `?` queries return booleans.\n\n## Run the Web Interpreter\n\nTo run the KGL web interpreter, first generate a knowledge graph in a CSV file. Each line should use the format `subject, predicate, object`. Then, open `app/app.py` and replace the `all1.csv` reference with the name of your CSV file. Then, install the required dependencies:\n\n```\ncd app/\npip3 install -r requirements.txt\n```\n\nTo run the web interpreter, execute the following command:\n\n```\npython3 app.py\n```\n\nThe interpreter will open at `http://localhost:5000`.\n\n## Tests\n\nTo run the project test suite, run:\n\n```\npytest test/test.py\n```\n\n## License\n\nThis project is licensed under an [MIT license](LICENSE).\n","funding_links":[],"categories":["\u003ca name=\"Python\"\u003e\u003c/a\u003ePython"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapjamesg%2Fknowledge-graph-language","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapjamesg%2Fknowledge-graph-language","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapjamesg%2Fknowledge-graph-language/lists"}