# neo4j-graphql.js API Reference

This reference documents the exports from `neo4j-graphql-js`:

## Exports

### `makeAugmentedSchema(options)`: <`GraphQLSchema`>

Wraps [`makeExecutableSchema`](https://www.apollographql.com/docs/apollo-server/api/apollo-server.html#makeExecutableSchema) to create a GraphQL schema from GraphQL type definitions (SDL). Will generate Query and Mutation types for the provided type definitions and attach `neo4jgraphql` as the resolver for these queries and mutations. Either a schema or typeDefs must be provided. `resolvers` can optionally be implemented to override any of the generated Query/Mutation fields. Additional options are passed through to `makeExecutableSchema`.

#### Parameters

- `options`: <`Object`>
  - `schema`: <`GraphQLSchema`>
  - `typeDefs`: <`String`>
  - `resolvers`: <`Object`>
  - `logger`: <`Object`>
  - `allowUndefinedInResolve` = false
  - `resolverValidationOptions` = {}
  - `directiveResolvers` = null
  - `schemaDirectives` = null
  - `parseOptions` = {}
  - `inheritResolversFromInterfaces` = false
  - `config`: <`Object`> = {}

#### config

`config` is an object that can contain several optional keys as detailed in the table below.

| Key        | Description                                                                                                                                                                                                                                                                                                                                                                                                  | Default | Options               | Example                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --------------------- | ----------------------------------------------------------------------------------- |
| `query`    | Configure the autogenerated Query fields. Can be enabled/disabled for all types or a list of individual types to exclude can be passed. Commonly used to exclude payload types.                                                                                                                                                                                                                              | `true`  | `Boolean` or `Object` | `{query: false}`<br></br><br></br> `{query: {exclude: ["MyPayloadType"]}`           |
| `mutation` | Configure the autogenerated Mutation fields. Can be enabled/disabled for all types or a list of individual types to exclude can be passed. Commonly used to exclude payload types.                                                                                                                                                                                                                           | `true`  | `Boolean` or `Object` | `{mutation: false}` <br></br><br></br> `{query: {exclude: ["MyPayloadType"]}`       |
| `debug`    | Enable/disable logging of generated Cypher queries and parameters.                                                                                                                                                                                                                                                                                                                                           | `True`  | `Boolean`             | `{debug: false}`                                                                    |
| `auth`     | Used to enable authorization schema directives (`@isAuthenticated`, `@hasRole`, `@hasScope`). If enabled, directives from the [graphql-auth-directives](https://www.npmjs.com/package/graphql-auth-directives) are declared and can be used in the schema. If `@hasScope` is enabled it is automatically added to all generated query and mutation fields. See the authorization guide for more information. | `false` | `Boolean` or `Object` | `{auth: true}` <br></br><br></br> `{auth: {isAuthenticated: true}, {hasRole: true}` |

For example:

```js
const schema = makeAugmentedSchema({
  typeDefs,
  config: {
    query: true, //default
    mutation: false
  }
});
```

or

```js
const schema = makeAugmentedSchema({
  typeDefs,
  config: {
    query: {
      exclude: ['MyPayloadType']
    },
    mutation: {
      exclude: ['MyPayloadType']
    }
  }
});
```

#### Returns

`GraphQLSchema`

<hr></hr>

### `assertSchema(options)`:`null`

This function uses the `@id`, `@unique`, and `@index` schema directives present in the GraphQL type definitions, along with [apoc.schema.assert()](https://neo4j.com/labs/apoc/4.0/overview/apoc.schema/apoc.schema.assert/), to add any database constraints and indexes.

#### Parameters

- `options`: <`Object`>

  - `schema`: <`GraphQLSchema`>
  - `driver`: <`Neo4jDriver`>
  - `debug`: <`Bool`> = false
  - `dropExisting`: <`Bool`> = true

#### Example

```js
import {
  makeAugmentedSchema,
  assertSchema
} from 'neo4j-graphql-js';

const driver = neo4j.driver(...);

const schema = makeAugmentedSchema(...);

assertSchema({ schema, driver, debug: true });
```

<hr></hr>

### `searchSchema(options)`:`null`

This function uses the `@search` schema directive present in the GraphQL type definitions to add any [full-text search indexes](https://neo4j.com/docs/cypher-manual/current/administration/indexes-for-full-text-search/).

#### Parameters

- `options`: <`Object`>

  - `schema`: <`GraphQLSchema`>
  - `driver`: <`Neo4jDriver`>
  - `debug`: <`Bool`> = false

#### Example

```js
import {
  makeAugmentedSchema,
  searchSchema
} from 'neo4j-graphql-js';

const driver = neo4j.driver(...);

const schema = makeAugmentedSchema(...);

searchSchema({ schema, driver, debug: true });
```

<hr></hr>

### `neo4jgraphql(object, params, context, resolveInfo, debug)`: <`ExecutionResult`>

This function's signature matches that of [GraphQL resolver functions](https://graphql.org/learn/execution/#root-fields-resolvers). and thus the parameters match the parameters passed into `resolve` by GraphQL implementations like graphql-js.

It can be called within a resolver to generate a Cypher query and handle the database call to Neo4j to completely resolve the GraphQL request. Alternatively, use `cypherQuery` or `cypherMutation` within a resolver to only generate the Cypher query and handle the database call yourself.

#### Parameters

- `object`: <`Object`>

The previous object being resolved. Rarely used for a field on the root Query type.

- `params`: <`Object`>

The arguments provided to the field in the GraphQL query.

- `context`: <`Object`>

Value provided to every resolver and hold contextual information about the request, such as the currently logged in user, or access to a database. _`neo4j-graphql-js` assumes a `neo4j-javascript-driver` instance exists in this object, under the key `driver`._

- `resolveInfo`: <`GraphQLResolveInfo`>

Holds field-specific infomation relevant to the current query as well as the GraphQL schema.

- `debug`: `Boolean` _(default: `true`)_

Specifies whether to log the generated Cypher queries for each GraphQL request. Logging is enabled by default.

#### Returns

[ExecutionResult](https://graphql.org/graphql-js/execution/#execute)

<hr></hr>

### `augmentSchema(schema, config)`: <`GraphQLSchema`>

Takes an existing GraphQL schema object and adds neo4j-graphql-js specific enhancements, including auto-generated mutations and queries, and ordering and pagination fields. See [this guide](neo4j-graphql-js.mdx) for more information.

> NOTE: Only use `augmentSchema` if you are working with an existing GraphQLSchema object. In most cases you should use [`makeAugmentedSchema`](#makeaugmentedschemaoptions-graphqlschema) which can construct the GraphQLSchema object from type definitions.

#### Parameters

- `schema`: <`GraphQLSchema`>
- `config`: <`Object`>

`config` is an object that can contain several optional keys. See the [details in the table below for `makeAugmentedSchema`](#config)

For example:

```js
const augmentedSchema = augmentSchema(schema, {
  query: true, //default
  mutation: false
});
```

or

```js
const augmentedSchema = augmentSchema(schema, {
  query: {
    exclude: ['MyPayloadType']
  },
  mutation: {
    exclude: ['MyPayloadType']
  }
});
```

#### Returns

`GraphQLSchema`

<hr></hr>

### `cypherQuery(params, context, resolveInfo)`

Generates a Cypher query (and associated parameters) to resolve a given GraphQL request (for a Query). Use this function when you want to handle the database call yourself, use `neo4jgraphql` for automated database call support.

#### Parameters

- `params`: <`Object`>
- `context`: <`Object`>
- `resolveInfo`: <`GraphQLResolveInfo`>

#### Returns

`[`<`String`>, <`Object`>`]`

Returns an array where the first element is the genereated Cypher query and the second element is an object with the parameters for the generated Cypher query.

<hr></hr>

### `cypherMutation(params, context, resolveInfo`

Similar to `cypherQuery`, but for mutations. Generates a Cypher query (and associated parameters) to resolve a given GraphQL request (for a Mutation). Use this function when you want to handle the database call yourself, use `neo4jgraphql` for automated database call support.

#### Parameters

- `params`: <`Object`>
- `context`: <`Object`>
- `resolveInfo`: <`GraphQLResolveInfo`>

#### Returns

`[`<`String`>, <`Object`>`]`

Returns an array where the first element is the genereated Cypher query and the second element is an object with the parameters for the generated Cypher query.

<hr></hr>

### `inferSchema(driver, [options])`: <`Promise`>

Used to generate GraphQL type definitions from an existing Neo4j database by inspecting the data stored in the database. When used in combination with `makeAugmentedSchema` this can be used to generate a GraphQL CRUD API on top of an existing Neo4j database without writing any resolvers or GraphQL type definitions. See [example/autogenerated/autogen.js](https://github.com/neo4j-graphql/neo4j-graphql-js/blob/master/example/autogenerated/autogen.js) for an example of using `inferSchema` and `makeAugmentedSchema` with Apollo Server.

#### Parameters

- `driver`: <`Neo4jDriver`>
- `options`: <`Object`>
  - `alwaysIncludeRelationships`: `Boolean` - specifies whether relationships should always be included in the type definitions as [relationship types](neo4j-graphql-js.mdx#relationship-types), even if the relationships do not have properties.

#### Returns

`Promise` that resolves to an object that contains:

- `typeDefs`: `String` - a string representation of the generated GraphQL type definitions in Schema Definition Language (SDL) format, inferred from the existing Neo4j database.