{"id":18798017,"url":"https://github.com/polypheny/polypheny-ipython","last_synced_at":"2026-01-01T20:30:15.917Z","repository":{"id":196984502,"uuid":"639774969","full_name":"polypheny/Polypheny-IPython","owner":"polypheny","description":"IPython extension  that allows to query Polypheny using any of the supported query languages directly from within Jupyter notebooks.","archived":false,"fork":false,"pushed_at":"2023-10-11T09:22:54.000Z","size":30,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-29T18:15:26.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polypheny.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,"governance":null}},"created_at":"2023-05-12T07:43:39.000Z","updated_at":"2023-09-28T11:15:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"8f09eca0-27d3-472d-ba66-61d7b9a8c969","html_url":"https://github.com/polypheny/Polypheny-IPython","commit_stats":null,"previous_names":["polypheny/polypheny-ipython"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polypheny%2FPolypheny-IPython","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polypheny%2FPolypheny-IPython/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polypheny%2FPolypheny-IPython/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polypheny%2FPolypheny-IPython/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polypheny","download_url":"https://codeload.github.com/polypheny/Polypheny-IPython/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239727047,"owners_count":19687098,"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-11-07T22:10:35.430Z","updated_at":"2026-01-01T20:30:13.865Z","avatar_url":"https://github.com/polypheny.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://polypheny.org/\"\u003e\n        \u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/polypheny/Admin/master/Logo/logo-white-text_cropped.png\"\u003e\n            \u003cimg width='50%' alt=\"Light: 'Resume application project app icon' Dark: 'Resume application project app icon'\" src=\"https://raw.githubusercontent.com/polypheny/Admin/master/Logo/logo-transparent_cropped.png\"\u003e\n        \u003c/picture\u003e\n    \u003c/a\u003e    \n\u003c/p\u003e \n\n# Polypheny Extension for IPython\nThis IPython extension adds `%poly` magics for querying [Polypheny](https://polypheny.org/) using any of the supported query languages. This extension takes inspiration from the brilliant [IPython SQL Extension](https://github.com/catherinedevlin/ipython-sql).\n\n## Installation\n\n### Via PyPi\nThe recommended way to install the package is with pip:\n```bash\npip install ipython-polypheny\n```\n\n### From Source\nIf you do not want to use pip, you can download the code and build it manually.\n\n1. Download the source code.\n2. At the root directory, run python -m build. This will produce .tar.gz and .whl files in the dist/ folder.\n3. Install the package using: python -m pip install ./dist/\u003cfile-name\u003e.whl.\n\n## Usage\nActivate the extension using:\n```python\n%load_ext poly\n```\n\nYou can utilize both line magics (%poly) and cell magics (%%poly). A command must always follow the magic keyword. For instance: \n```python\n# Print help\n%poly help\n```\n\nCommands requiring arguments should separate them using a colon (:):\n```python\n# Specify the http-interface address of a running Polypheny instance.\n%poly db: http://localhost:13137\n```\n\nThe colon can also be replaced by a line break when using cell magics.\nThis is the ideal syntax for querying the database, where the command specifies the query language:\n```python\n%%poly sql\nSELECT * FROM emps\n```\nThe result is automatically printed as a nicely formatted table.\n\nInteract with the retrieved data in multiple ways:\n\nStoring the result in a variable:\n```python\nresult = _\n\n# Or when using line magics (note the required colon that separates the query from the command):\nresult = %poly sql: SELECT * FROM emps\n```\n\nAdditionally to the query language, a namespace can be specified. \nIt is also possible to set flags. The `-c` flag deactivates the cache for this query:\n```python\n%%poly mql mynamespace -c\ndb.emps.find({})\n```\n\n### Working With the Result\nThe result object provides useful ways to work with the retrieved data.  \n```python\nresult = %poly sql: SELECT * FROM emps\n```\nGetting the raw `ResultSet`:\n```python\nresult.result_set\n```\nThe data can be accessed like a two-dimensional `list`:\n```python\n# get the value of the element in the first row and second column\nresult[0][1]\n```\nIterate over the rows as `dict`s:\n```python\nfor employee in result.dicts():\n    print(employee['name'], employee['salary'])\n```\n\nProvided [Pandas](https://pypi.org/project/pandas/) is installed, it is possible to transform the result into a `DataFrame`:\n```python\ndf = result.as_df()\n```\n\n### Advanced Features\n\nIt is possible to expand variables defined in the local namespace into a query.\nFor this to work, the `--template` (shorter: `-t`) flag must be set:\n```python\nkey = 'salary'\nx = 10000\n\n%% poly -t sql: SELECT * FROM emps WHERE ${key} \u003e ${x}\n\n# is equal to\n%% poly sql: SELECT * FROM emps WHERE salary \u003e 10000\n```\nBe careful to not accidentally inject unwanted queries, as the values are not escaped.\n\n## Data Types\nPolypheny's data types are mapped to Python's as follows:\n\n| Type in Polypheny                          | Type in Python  |\n|:-------------------------------------------|:----------------|\n| `BIGINT`, `INTEGER`, `SMALLINT`, `TINYINT` | `int`           |\n| `DECIMAL`, `DOUBLE`, `REAL`                | `float`         |\n| `BOOLEAN`                                  | `bool`          |\n| `DOCUMENT`, `JSON`, `NODE`, `PATH`         | `dict`          |\n| `ARRAY`                                    | `list`          |\n\nOther types are stored as str. Failed casting operations will also result in str.  If the raw data as a nested `list` of `str` is required, one can get it from the `ResultSet`:\n```python\nraw_data = result.result_set['data']\n```\n\n### Limitations\nWorking with multimedia and other blob types is currently not supported. While it does not result in an error, only the identifier is stored, not the actual content.\n\n\n## Contributing\nThank you for considering contributing! We truly appreciate any effort, whether it's fixing bugs, improving documentation, or suggesting new features. Here's a guide to help streamline the process:\n\n1. **Start by Forking**: Begin by forking the repository. Once done, you can work on your changes and then submit them as a pull request.\n\n2. **Development Guidelines**: Before diving in, take a moment to explore our [Documentation](https://docs.polypheny.com). Pay special attention to the 'For Developers' section — it offers insights on setup, code style, organization, and other valuable resources tailored for developers.\n\n3. **Adherence to Code of Conduct**: We are committed to fostering an open and welcoming environment. As such, we request all contributors to uphold the standards outlined in our [code of conduct](https://github.com/polypheny/Admin/blob/master/CODE_OF_CONDUCT.md) throughout their interactions related to the project.\n\n4. **Setting up for Development**:\n   - **Editable Installation**: To see your code changes reflected in real-time, install the extension in an editable mode. Execute the following command from the root directory of the extension:\n     ```bash\n     python -m pip install -e .\n     ```\n     This allows any modifications in the codebase to be instantly visible post-reloading the extension.\n     \n   - **Utilize Autoreload**: For a smoother development experience, consider activating the [autoreload](https://ipython.org/ipython-doc/3/config/extensions/autoreload.html) extension. This tool automatically reloads the extension and incorporates the recent code changes:\n     ```python\n     %load_ext autoreload\n     %autoreload 2\n     %load_ext poly\n     ```\n\nThank you for your dedication and enthusiasm for enhancing the Polypheny ecosystem! We look forward to reviewing your valuable contributions.\n\n## License\nThe Apache 2.0 License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolypheny%2Fpolypheny-ipython","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolypheny%2Fpolypheny-ipython","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolypheny%2Fpolypheny-ipython/lists"}