graphql-compiler

|Build Status| |Coverage Status| |License| |PyPI Python| |PyPI Version| |PyPI Status| |PyPI Wheel| |Code Style|

Turn complex GraphQL queries into optimized database queries.

::

pip install graphql-compiler

Quick Overview

GraphQL compiler is a library that simplifies data querying and exploration by exposing one simple query language written using GraphQL syntax to target multiple database backends. It currently supports OrientDB <https://graphql-compiler.readthedocs.io/en/latest/supported_databases/orientdb.html>. and multiple SQL <https://graphql-compiler.readthedocs.io/en/latest/supported_databases/sql.html> database management systems, such as PostgreSQL, MSSQL and MySQL.

For a detailed overview, see our blog post <https://blog.kensho.com/compiled-graphql-as-a-database-query-language-72e106844282>. To get started, see our Read the Docs documentation <https://graphql-compiler.readthedocs.io/en/latest/>. To contribute, please see our contributing guide <https://graphql-compiler.readthedocs.io/en/latest/about/contributing.html>__.

Examples

.. HACK: To avoid duplicating the end-to-end examples, we use the `include` restructured text
         directive. We add the comments below to mark the start and end of the text that the
         `include` directive has to copy. An alternative here would be to add an examples directory
         and "include" the examples from there in both the README and Read the Docs. However, github
         does not support the `include` directive: https://github.com/github/markup/issues/172

OrientDB
^^^^^^^^

.. end-to-end-orientdb-example-start

.. code:: python

    from graphql.utils.schema_printer import print_schema
    from graphql_compiler import (
        get_graphql_schema_from_orientdb_schema_data, graphql_to_match
    )
    from graphql_compiler.schema.schema_info import CommonSchemaInfo
    from graphql_compiler.schema_generation.orientdb.utils import ORIENTDB_SCHEMA_RECORDS_QUERY

    # Step 1: Get schema metadata from hypothetical Animals database.
    client = your_function_that_returns_an_orientdb_client()
    schema_records = client.command(ORIENTDB_SCHEMA_RECORDS_QUERY)
    schema_data = [record.oRecordData for record in schema_records]

    # Step 2: Generate GraphQL schema from metadata.
    schema, type_equivalence_hints = get_graphql_schema_from_orientdb_schema_data(schema_data)

    print(print_schema(schema))
    # schema {
    #    query: RootSchemaQuery
    # }
    #
    # directive @filter(op_name: String!, value: [String!]!) on FIELD | INLINE_FRAGMENT
    #
    # directive @tag(tag_name: String!) on FIELD
    #
    # directive @output(out_name: String!) on FIELD
    #
    # directive @output_source on FIELD
    #
    # directive @optional on FIELD
    #
    # directive @recurse(depth: Int!) on FIELD
    #
    # directive @fold on FIELD
    #
    # type Animal {
    #     name: String
    #     net_worth: Int
    #     limbs: Int
    # }
    #
    # type RootSchemaQuery{
    #     Animal: [Animal]
    # }

    # Step 3: Write GraphQL query that returns the names of all animals with a certain net worth.
    # Note that we prefix net_worth with '$' and surround it with quotes to indicate it's a parameter.
    graphql_query = '''
    {
        Animal {
            name @output(out_name: "animal_name")
            net_worth @filter(op_name: "=", value: ["$net_worth"])
        }
    }
    '''
    parameters = {
        'net_worth': '100',
    }

    # Step 4: Use autogenerated GraphQL schema to compile query into the target database language.
    common_schema_info = CommonSchemaInfo(schema, type_equivalence_hints)
    compilation_result = graphql_to_match(common_schema_info, graphql_query, parameters)
    print(compilation_result.query)
    # SELECT Animal___1.name AS `animal_name`
    # FROM  ( MATCH  { class: Animal, where: ((net_worth = decimal("100"))), as: Animal___1 }
    # RETURN $matches)

.. end-to-end-orientdb-example-end

SQL
^^^

.. end-to-end-sql-example-start

.. code:: python

    from graphql_compiler import get_sqlalchemy_schema_info, graphql_to_sql
    from sqlalchemy import MetaData, create_engine

    engine = create_engine('<connection string>')

    # Reflect the default database schema. Each table must have a primary key. Otherwise see:
    # https://graphql-compiler.readthedocs.io/en/latest/supported_databases/sql.html#including-tables-without-explicitly-enforced-primary-keys
    metadata = MetaData(bind=engine)
    metadata.reflect()

    # Wrap the schema information into a SQLAlchemySchemaInfo object.
    sql_schema_info = get_sqlalchemy_schema_info(metadata.tables, {}, engine.dialect)

    # Write GraphQL query.
    graphql_query = '''
    {
        Animal {
            name @output(out_name: "animal_name")
        }
    }
    '''
    parameters = {}

    # Compile and execute query.
    compilation_result = graphql_to_sql(sql_schema_info, graphql_query, parameters)
    query_results = [dict(row) for row in engine.execute(compilation_result.query)]

.. end-to-end-sql-example-end

License
-------

Licensed under the Apache 2.0 License. Unless required by applicable law
or agreed to in writing, software distributed under the License is
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the specific
language governing permissions and limitations under the License.

Copyright 2017-present Kensho Technologies, LLC. The present date is
determined by the timestamp of the most recent commit in the repository.

.. |Build Status| image:: https://github.com/kensho-technologies/graphql-compiler/workflows/Tests%20and%20lint/badge.svg
   :target: https://github.com/kensho-technologies/graphql-compiler/actions?query=workflow%3A%22Tests+and+lint%22
.. |Coverage Status| image:: https://codecov.io/gh/kensho-technologies/graphql-compiler/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/kensho-technologies/graphql-compiler
.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
   :target: https://opensource.org/licenses/Apache-2.0
.. |PyPI Python| image:: https://img.shields.io/pypi/pyversions/graphql-compiler.svg
   :target: https://pypi.python.org/pypi/graphql-compiler
.. |PyPI Version| image:: https://img.shields.io/pypi/v/graphql-compiler.svg
   :target: https://pypi.python.org/pypi/graphql-compiler
.. |PyPI Status| image:: https://img.shields.io/pypi/status/graphql-compiler.svg
   :target: https://pypi.python.org/pypi/graphql-compiler
.. |PyPI Wheel| image:: https://img.shields.io/pypi/wheel/graphql-compiler.svg
   :target: https://pypi.python.org/pypi/graphql-compiler
.. |Code Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Code style: black