{"id":19724754,"url":"https://github.com/bigchaindb/js-bigchaindb-graphql","last_synced_at":"2025-04-29T23:30:28.339Z","repository":{"id":143856728,"uuid":"99207451","full_name":"bigchaindb/js-bigchaindb-graphql","owner":"bigchaindb","description":"A GraphQL interface for BigchainDB in JavaScript","archived":false,"fork":false,"pushed_at":"2019-05-24T22:45:11.000Z","size":174,"stargazers_count":18,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-19T06:19:26.711Z","etag":null,"topics":["bigchaindb","graphql","json","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"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/bigchaindb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-03T08:05:35.000Z","updated_at":"2023-10-31T02:11:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"120a4ec5-fee7-4adc-b012-57cc04562dba","html_url":"https://github.com/bigchaindb/js-bigchaindb-graphql","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/bigchaindb%2Fjs-bigchaindb-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigchaindb%2Fjs-bigchaindb-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigchaindb%2Fjs-bigchaindb-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigchaindb%2Fjs-bigchaindb-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigchaindb","download_url":"https://codeload.github.com/bigchaindb/js-bigchaindb-graphql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251599654,"owners_count":21615563,"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":["bigchaindb","graphql","json","nodejs"],"created_at":"2024-11-11T23:26:56.197Z","updated_at":"2025-04-29T23:30:28.314Z","avatar_url":"https://github.com/bigchaindb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [![js-bigchaindb-graphql](media/repo-banner@2x.png)](https://www.bigchaindb.com)\n\n\u003e Example GraphQL API running on top of the BigchainDB JavaScript driver.\n\n[![npm](https://img.shields.io/npm/v/bigchaindb-graphql.svg)](https://www.npmjs.com/package/bigchaindb-graphql)\n[![Build Status](https://travis-ci.org/bigchaindb/js-bigchaindb-graphql.svg?branch=master)](https://travis-ci.org/bigchaindb/js-bigchaindb-graphql)\n[![js ascribe](https://img.shields.io/badge/js-ascribe-39BA91.svg)](https://github.com/ascribe/javascript)\n[![Greenkeeper badge](https://badges.greenkeeper.io/bigchaindb/js-bigchaindb-graphql.svg)](https://greenkeeper.io/)\n\n## Table of Contents\n\n- [Setup](#setup)\n- [Usage](#usage)\n- [Examples](#examples)\n    - [Query a transaction](#query-a-transaction)\n    - [Query multiple transactions by `asset_id`](#query-multiple-transactions-by-asset_id)\n    - [Query only transfer transactions with `asset_id`](#query-only-transfer-transactions-with-asset_id)\n    - [Query the blocks and votes for a transaction](#query-the-blocks-and-votes-for-a-transaction)\n    - [Query the outputs endpoint by public key](#query-the-outputs-endpoint-by-public-key)\n    - [Query the outputs endpoint by public key](#query-the-outputs-endpoint-by-public-key-1)\n    - [Query a block and the associated votes](#query-a-block-and-the-associated-votes)\n    - [Query the votes for a specific block](#query-the-votes-for-a-specific-block)\n    - [Text-search on transactions that matches the asset fields/values](#text-search-on-transactions-that-matches-the-asset-fieldsvalues)\n    - [Create a new transaction](#create-a-new-transaction)\n    - [Transfer transaction different public key](#transfer-transaction-different-public-key)\n- [npm releases](#npm-releases)\n- [License](#license)\n\n## Setup\n\n```bash\n$ npm install bigchaindb-graphql\n```\n\nor\n\n```bash\n$ yarn add bigchaindb-graphql\n```\n\n(Optional) Prepopulate BigchainDB with the example transactions, see [bigchaindb/graphql-bigchaindb](https://github.com/bigchaindb/graphql-bigchaindb):\n\n```bash\n$ python prepopulate.py\n```\nThese are the transactions used in the examples below.\n\n```bash\n$ npm run test\n```\n\n## Usage\n\nThe code does not talk to the backend database directly. It just retrieves whatever data it needs using the JavaScript driver and constructs the GraphQL objects from the returned JSON.\n\n```javascript\nimport { graphql } from 'graphql'\nimport {\n    BigchainDBGraphQLConnection,\n    BigchainDBGraphQLSchema\n} from 'bigchaindb-graphql'\n\nconst BigchainDBSchema = new BigchainDBGraphQLSchema(\n    new BigchainDBGraphQLConnection(\"\u003cconnection details eg. 'http://localhost:9984/api/v1/', headers\u003e\")\n).schema\n\nconst queryTransaction = `\n{\n    transaction(id: \"3b3fd7128580280052595b9bcda98895a851793cba77402ca4de0963be958c9e\") {\n        id\n        operation\n        asset\n        metadata\n    }\n}\n`\n\ngraphql(BigchainDBSchema, queryTransaction).then(result =\u003e {\n    console.log(JSON.stringify(result, null, 2))\n})\n```\n\n## Examples\n\nAfter prepopulating BigchainDB with the transactions provided you can run the following queries in the browser or Node.js.\n\n### Query a transaction\n\n```graphql\nquery {\n    transaction(id:\"3b3fd7128580280052595b9bcda98895a851793cba77402ca4de0963be958c9e\") {\n        id\n        operation\n        asset\n        # we don't care about the inputs\n        # inputs\n\n        # from the outputs we don't care about the condition so we only want\n        # the amount and public keys\n        outputs {\n            amount\n            public_keys\n        }\n\n        # we don't care about the metadata\n        # metadata\n    }\n}\n```\n\n### Query multiple transactions by `asset_id`\n\n```graphql\nquery {\n    transactions(asset_id:\"3b3fd7128580280052595b9bcda98895a851793cba77402ca4de0963be958c9e\") {\n        # For each transaction returned I only want the id, operation and\n        # public keys in the outputs\n        id\n        operation\n        outputs {\n            public_keys\n        }\n    }\n}\n```\n\n### Query only transfer transactions with `asset_id`\n\n```graphql\nquery {\n    transactions(asset_id:\"3b3fd7128580280052595b9bcda98895a851793cba77402ca4de0963be958c9e\", operation:\"TRANSFER\") {\n        # I only want the public keys and amounts of all the outputs that this\n        # transfer transaction fulfills\n        inputs {\n            fulfills {\n                output_index\n                # the `transaction_id` inside fulfills is resolved to the\n                # actual transaction so we can query fields on the transaction\n                # pointed to in this inputs, notice that this can go as deep as you like\n                transaction {\n                    outputs {\n                        amount\n                        public_keys\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\n### Query the blocks and votes for a transaction\n\n```graphql\nquery {\n    transaction(id:\"3b3fd7128580280052595b9bcda98895a851793cba77402ca4de0963be958c9e\") {\n        # I want to know the blocks, votes and respective timestamps of a transaction\n        asset\n        metadata\n        blocks {\n            block {\n                node_pubkey\n                timestamp\n            }\n            votes {\n                node_pubkey\n                vote {\n                    timestamp\n                }\n            }\n        }\n    }\n}\n```\n\n### Query the outputs endpoint by public key\n\n```graphql\nquery {\n    outputs(publicKey:\"FxEfUt9ArymGeCB99dZtfCUcsKwC29c8AHZ9EPnVWcyL\") {\n        output_index\n        # once again the transaction_id is resolved to the actual transaction\n        transaction {\n           id\n           operation\n           asset\n        }\n    }\n}\n```\n\n### Query the outputs endpoint by public key\n\n```graphql\nquery {\n    outputs(publicKey:\"FxEfUt9ArymGeCB99dZtfCUcsKwC29c8AHZ9EPnVWcyL\") {\n        output_index\n        # once again the transaction_id is resolved to the actual transaction\n        transaction {\n           id\n           operation\n           asset\n        }\n    }\n}\n```\n\n### Query a block and the associated votes\n\n```graphql\nquery {\n    block(id: \"c44c06985175ee0cf210fff65c44e63aa06300999e5e7654e13678582522e8f0\") {\n        id\n        block {\n            timestamp\n            transactions {\n                id\n            }\n            node_pubkey\n            voters\n        }\n        votes {\n            vote {\n                timestamp\n            }\n        }\n        signature\n    }\n}\n```\n\n### Query the votes for a specific block\n\n```graphql\nquery {\n    votes(block_id: \"c44c06985175ee0cf210fff65c44e63aa06300999e5e7654e13678582522e8f0\") {\n        node_pubkey\n        signature\n        vote {\n            voting_for_block\n            previous_block\n            is_block_valid\n            invalid_reason\n            timestamp\n        }\n    }\n}\n```\n\n### Text-search on transactions that matches the asset fields/values\n\n```graphql\nquery {\n    search(text: \"b\") {\n        id\n        asset\n    }\n}\n```\n\n### Create a new transaction\n\u003e note: graphql doesn't support unstructured objects, hence the `asset` and `metadata` need to be serialized in an URI encoded string (e.g. `encodeURIComponent(JSON.stringify({ metadata: 'metavalue' }))`)\n\n```graphql\nmutation {\n    transaction(\n        publicKey: \"4AzdUiGGjUNmSp75dNGe5Qw36czV8PdaLDkCY2bdZpcH\",\n        privateKey: \"57c3KBq7hiQ7JLHuVWzBGfwCKeLfm1oFbv9CgP2uxwhN\",\n        asset: \"{ assetdata: 'assetvalue' }\",\n        metadata: \"{ metadata: 'metavalue' }\"\n    ) {\n        id\n        operation\n        asset\n        metadata\n        inputs {\n            owners_before\n            fulfillment\n            fulfills {\n                output_index\n                transaction {\n                    id\n                    asset\n                    metadata\n                    inputs {\n                        fulfills {\n                            transaction {\n                                id\n                            }\n                        }\n                    }\n                }\n            }\n        }\n        outputs {\n            condition\n            public_keys\n            amount\n        }\n        blocks {\n            block {\n                node_pubkey\n                timestamp\n            }\n            votes {\n                node_pubkey\n                vote {\n                    timestamp\n                }\n            }\n        }\n    }\n}\n```\n\n### Transfer transaction different public key\n\u003e note: graphql doesn't support unstructured objects, hence the `tx` and `metadata` need to be serialized in an URI encoded string (e.g. `encodeURIComponent(JSON.stringify(tx))`)\n```graphql\nmutation {\n    transfer(\n        tx: \u003ctransaction to transfer\u003e,\n        fromPublicKey: \"8bpyjMowghbfN8vMTAyueQVggjtR9geACU8JeXLQHawY\",\n        fromPrivateKey: \"DQGfjg1kseHZTedxsUjwTXukGZ8hPNjioJ7Btq9wyiTW\",\n        toPublicKey: \"GvjRh229J3GEgGnSjKzdv81eiEUtjyftBsJzU2Urmfud\",\n        metadata: \"{metadata: 'newmetavalue'}\"\n    ) {\n        id\n        operation\n        asset\n        metadata\n        inputs {\n            owners_before\n            fulfillment\n            fulfills {\n                output_index\n                transaction {\n                    id\n                    asset\n                    metadata\n                    inputs {\n                        fulfills {\n                            transaction {\n                                id\n                            }\n                        }\n                    }\n                }\n            }\n        }\n        outputs {\n            condition\n            public_keys\n            amount\n        }\n        blocks {\n            block {\n                node_pubkey\n                timestamp\n            }\n            votes {\n                node_pubkey\n                vote {\n                    timestamp\n                }\n            }\n        }\n    }\n}\n```\n\n## npm releases\n\nFor a new **patch release**, execute on the machine where you're logged into your npm account:\n\n```bash\nnpm run release\n```\n\nCommand is powered by [`release-it`](https://github.com/webpro/release-it) package, defined in the `package.json`.\n\nThat's what the command does without any user interaction:\n\n- create release commit by updating version in `package.json`\n- create tag for that release commit\n- push commit \u0026 tag\n- create a new release on GitHub, with change log auto-generated from commit messages\n- publish to npm as a new release\n\nIf you want to create a **minor** or **major release**, use these commands:\n\n```bash\nnpm run release-minor\n```\n\n```bash\nnpm run release-major\n```\n\n## License\n\n```\nCopyright 2017 BigchainDB GmbH\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigchaindb%2Fjs-bigchaindb-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigchaindb%2Fjs-bigchaindb-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigchaindb%2Fjs-bigchaindb-graphql/lists"}