Uso delle direttive per uno schema GraphQL

Puoi iniziare da uno schema GraphQL che contiene già delle direttive, usando un comando come questo:

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

Puoi modificare le direttive create dall'utilità o aggiungere direttive personalizzate a uno schema GraphQL. Di seguito sono descritti alcuni modi per usare le direttive:

Esecuzione dell'utilità in modo che non generi mutazioni

Per impedire all'utilità di generare mutazioni nell'API GraphQL, usa l'opzione --output-schema-no-mutations nel comando neptune-for-graphql.

Direttiva @alias

La direttiva @alias può essere applicata ai tipi o ai campi dello schema GraphQL. Essa esegue la mappatura di nomi diversi tra il database a grafo e lo schema GraphQL. La sintassi è:

@alias(property: (property name))

Nell'esempio seguente, airport è l'etichetta del nodo del database a grafo mappata al tipo GraphQL Airport, mentre desc è la proprietà del nodo del grafo mappata al campo description (consulta l'esempio per Air Routes):

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

Nota che la formattazione GraphQL standard richiama nomi di tipo Pascal-casing e nomi di campo camel-casing.

Direttiva @relationship

La direttiva @relationship mappa i tipi GraphQL annidati agli archi del database a grafo. La sintassi è:

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

Di seguito è illustrato un esempio di comando:

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)
}

Puoi trovare le direttive @relationship sia nell'esempio Todo che nell'esempio Air Routes.

Direttive @graphQuery e @cypher

Puoi definire query openCypher per risolvere un valore di campo, aggiungere query o aggiungere mutazioni. Ad esempio, puoi aggiungere un nuovo campo outboundRoutesCount al tipo Airport per contare le route in uscita:

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

Di seguito è riportato un esempio con nuove query e mutazioni:

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")
}

Nota: se ometti RETURN, il resolver presume che la parola chiave this sia l'ambito di restituzione.

Puoi anche aggiungere una query o una mutazione usando una query 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
}

Al momento le query Gremlin sono limitate a quelle che restituiscono valori scalari, ovvero elementMap() per un singolo nodo o elementMap().fold() per un elenco di nodi.

Direttiva @id

La direttiva @id identifica il campo mappato all'entità del database a grafo id. I database a grafo come Amazon Neptune hanno sempre un id univoco per nodi e archi che viene assegnato durante le importazioni in blocco o generato automaticamente. Per esempio:

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

Nomi di tipo, query e mutazione riservati

L'utilità genera automaticamente query e mutazioni per creare un'API GraphQL funzionante. Il modello di questi nomi è riconosciuto dal resolver ed è riservato. Di seguito sono riportati alcuni esempi del tipo Airport e del tipo di connessione Route:

Il tipo Options è riservato.

input Options {
  limit: Int
}

I parametri filter e options della funzione sono riservati.

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

Il prefisso getNode dei nomi delle query è riservato, e anche i prefissi dei nomi delle mutazioni comecreateNode, updateNode, deleteNode, connectNode, deleteNode, updateEdge e deleteEdge sono riservati.

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
}

Applicazione di modifiche allo schema GraphQL

Puoi modificare lo schema di origine GraphQL ed eseguire nuovamente l'utilità, ottenendo lo schema più recente dal database Neptune. Ogni volta che l'utilità rileva un nuovo schema nel database, genera un nuovo schema GraphQL.

Puoi anche modificare manualmente lo schema di origine GraphQL ed eseguire nuovamente l'utilità utilizzando come input lo schema di origine anziché l'endpoint del database Neptune.

Infine, puoi inserire le modifiche in un file utilizzando questo formato JSON:

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

Per esempio:

[
  {
    "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": ""
  }
]

Quindi, quando esegui l'utilità su questo file utilizzando il parametro --input-schema-changes-file nel comando, l'utilità applica le modifiche tutte insieme.