Trabajar con directivas para un esquema de GraphQL

Puede partir de un esquema de GraphQL que ya tenga directivas y utilizar un comando como el siguiente:

neptune-for-graphql \
  --input-schema-file (your GraphQL schema file with directives) \
  --create-update-aws-pipeline \
  --create-update-aws-pipeline-name (name for your new GraphQL API) \
  --create-update-aws-pipeline-neptune-endpoint  (empty Neptune database endpoint):(port number) \
  --output-resolver-query-https

Puede modificar las directivas que ha creado la utilidad o añadir sus propias directivas a un esquema de GraphQL. Estas son algunas de las formas de trabajar con las directivas:

Ejecutar la utilidad para que no genere mutaciones

Para evitar que la utilidad genere mutaciones en la API de GraphQL, utilice la opción --output-schema-no-mutations del comando neptune-for-graphql.

La directiva @alias

La directiva @alias se puede aplicar a campos o tipos de esquemas de GraphQL. Mapea diferentes nombres entre la base de datos de gráficos y el esquema de GraphQL. La sintaxis es la siguiente:

@alias(property: (property name))

En el siguiente ejemplo, airport es la etiqueta del nodo de la base de datos de gráficos mapeada al tipo Airport de GraphQL y desc es la propiedad del nodo de gráficos mapeada al campo description (consulte el ejemplo de rutas aéreas):

type Airport @alias(property: "airport") {
  city: String
  description: String @alias(property: "desc")
}

Tenga en cuenta que el formato estándar de GraphQL requiere nombres del tipo PascalCase y nombres de campo del tipo CamelCase.

La directiva @relationship

La directiva @relationship mapea los tipos de GraphQL anidados a los bordes de las bases de datos de gráficos. La sintaxis es la siguiente:

@relationship(edgeType: (edge name), direction: (IN or OUT))

A continuación se muestra un comando de ejemplo:

type Airport @alias(property: "airport") {
  ...
  continentContainsIn: Continent @relationship(edgeType: "contains", direction: IN)
  countryContainsIn: Country @relationship(edgeType: "contains", direction: IN)
  airportRoutesOut(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: OUT)
  airportRoutesIn(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: IN)
}

Puede encontrar las directivas @relationship tanto en el ejemplo de Todo como en el ejemplo de rutas aéreas.

Las directivas @graphQuery y @cypher

Puede definir consultas de openCypher para resolver un valor de campo, añadir consultas o añadir mutaciones. Por ejemplo, esto añade un campo nuevo outboundRoutesCount al tipo Airport para contar las rutas de salida:

type Airport @alias(property: "airport") {
  ...
  outboundRoutesCount: Int @graphQuery(statement: "MATCH (this)-[r:route]->(a) RETURN count(r)")
}

A continuación se muestra un ejemplo de nuevas consultas y mutaciones:

type Query {
  getAirportConnection(fromCode: String!, toCode: String!): Airport \
    @cypher(statement: \
      "MATCH (:airport{code: '$fromCode'})-[:route]->(this:airport)-[:route]->(:airport{code:'$toCode'})")
}

type Mutation {
  createAirport(input: AirportInput!): Airport @graphQuery(statement: "CREATE (this:airport {$input}) RETURN this")
  addRoute(fromAirportCode:String, toAirportCode:String, dist:Int): Route \
    @graphQuery(statement: \
     "MATCH (from:airport{code:'$fromAirportCode'}), (to:airport{code:'$toAirportCode'}) \
      CREATE (from)-[this:route{dist:$dist}]->(to) \
      RETURN this")
}

Tenga en cuenta que si omite RETURN, el solucionador asume que la palabra clave this es el ámbito de devolución.

También puede añadir una consulta o mutación mediante una consulta de Gremlin:

type Query {
  getAirportWithGremlin(code:String): Airport \
    @graphQuery(statement: "g.V().has('airport', 'code', '$code').elementMap()")  # single node
  getAirportsWithGremlin: [Airport] \
    @graphQuery(statement: "g.V().hasLabel('airport').elementMap().fold()")       # list of nodes
  getCountriesCount: Int \
    @graphQuery(statement: "g.V().hasLabel('country').count()")                   # scalar
}

En este momento, las consultas de Gremlin se limitan a las que devuelven valores escalares, o elementMap() a un solo nodo o elementMap().fold() a una lista de nodos.

La directiva @id

La directiva @id identifica el campo mapeado a la entidad de la base de datos de gráficos id. Las bases de datos de gráficos como Amazon Neptune siempre tienen un único id para los nodos y los bordes que se asignan durante las importaciones masivas o que se generan automáticamente. Por ejemplo:

type Airport {
  _id: ID! @id
  city: String
  code: String
}

Nombres reservados de tipos, consultas y mutaciones

La utilidad genera automáticamente consultas y mutaciones para crear una API de GraphQL que funcione. El solucionador reconoce el patrón de estos nombres y lo reserva. Estos son algunos ejemplos del tipo Airport y del tipo de conexión Route:

El tipo Options está reservado.

input Options {
  limit: Int
}

Los parámetros de la función filter y options están reservados.

type Query {
  getNodeAirports(filter: AirportInput, options: Options): [Airport]
}

El prefijo getNode de los nombres de consulta está reservado y los prefijos de los nombres de mutaciones como createNode, updateNode, deleteNode, connectNode, deleteNode, updateEdge y deleteEdge están reservados.

type Query {
  getNodeAirport(id: ID, filter: AirportInput): Airport
  getNodeAirports(filter: AirportInput): [Airport]
}

type Mutation {
  createNodeAirport(input: AirportInput!): Airport
  updateNodeAirport(id: ID!, input: AirportInput!): Airport
  deleteNodeAirport(id: ID!): Boolean
  connectNodeAirportToNodeAirportEdgeRout(from: ID!, to: ID!, edge: RouteInput!): Route
  updateEdgeRouteFromAirportToAirport(from: ID!, to: ID!, edge: RouteInput!): Route
  deleteEdgeRouteFromAirportToAirport(from: ID!, to: ID!): Boolean
}

Aplicación de cambios al esquema de GraphQL

Puede modificar el esquema de origen de GraphQL y volver a ejecutar la utilidad, obteniendo el esquema más reciente de la base de datos de Neptune. Cada vez que la utilidad detecta un nuevo esquema en la base de datos, genera un nuevo esquema de GraphQL.

También puede editar manualmente el esquema de origen de GraphQL y volver a ejecutar la utilidad con el esquema de origen como entrada en lugar del punto de conexión de la base de datos de Neptune.

Por último, puede introducir los cambios en un archivo con este formato JSON:

[
  {
    "type": "(GraphQL type name)",
    "field": "(GraphQL field name)",
    "action": "(remove or add)",
    "value": "(value)"
  }
]

Por ejemplo:

[
  {
    "type": "Airport",
    "field": "outboundRoutesCountAdd",
    "action": "add",
    "value":"outboundRoutesCountAdd: Int @graphQuery(statement: \"MATCH (this)-[r:route]->(a) RETURN count(r)\")"
  },
  {
    "type": "Mutation",
    "field": "deleteNodeVersion",
    "action": "remove",
    "value": ""
  },
  {
    "type": "Mutation",
    "field": "createNodeVersion",
    "action": "remove",
    "value": ""
  }
]

A continuación, al ejecutar la utilidad en este archivo con el parámetro --input-schema-changes-file del comando, la utilidad aplicará los cambios a la vez.