使用 GraphQL 結構描述的指令

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

您可以使用如下的命令，從已有指令的 GraphQL 結構描述開始：

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

您可以修改公用程式已建立的指令，或將您自己的指令新增至 GraphQL 結構描述。以下是一些使用指令的方法：

執行公用程式，以便它不會產生變動

若要防止公用程式在 GraphQL API 中產生變動，請在 neptune-for-graphql 命令中使用 --output-schema-no-mutations 選項。

@alias 指令

@alias 指令可以套用至 GraphQL 結構描述類型或欄位。它會在圖形資料庫與 GraphQL 結構描述之間映射不同的名稱。語法是：

@alias(property: (property name))

在下面範例中，airport 是映射到 Airport GraphQL 類型的圖形資料庫節點標籤，而 desc 是映射到 description 欄位的圖形節點屬性 (請參閱航線範例)：

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

請注意，標準 GraphQL 格式會要求 Pascal 大小寫類型名稱和駝峰式大小寫欄位名稱。

@relationship 指令

@relationship 指令會將巢狀 GraphQL 類型映射到圖形資料庫邊緣。語法是：

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

以下為範例命令：

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

您可以在 Todo 範例和航線範例中找到 @relationship 指令。

@graphQuery 和 @cypher 指令

您可以定義 OpenCypher 查詢來解析欄位值、新增查詢或新增變動。例如，這會將新的 outboundRoutesCount 欄位新增至 Airport 類型，以對傳出路由進行計數：

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

以下是新查詢和變動的範例

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

請注意，如果您省略了 RETURN，解析程式會假設關鍵字 this 是傳回範圍。

您也可以使用 Gemlin 查詢來新增查詢或變動：

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
}

目前，Gemlin 查詢限於傳回純量值或 elementMap() (若為單一節點) 或 elementMap().fold() (若為節點清單) 的查詢。

@id 指令

@id 指令會辨識映射到 id 圖形資料庫實體的欄位。圖形資料庫 (例如 Amazon Neptune) 對於在大量匯入期間指派或自動產生的節點和邊緣，永遠都有唯一的 id。例如：

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

保留類型、查詢和變動名稱

公用程式會自動產生查詢和變動，以建立運作的 GraphQL API。這些名稱的模式由解析程式辨識別並保留。以下是類型 Airport 和連線類型 Route 的範例：

Options 類型是保留的。

input Options {
  limit: Int
}

filter 和 options 函數參數是保留的。

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

查詢名稱的 getNode 字首是保留的，並且變動名稱 (例如 createNode、updateNode、deleteNode、connectNode、deleteNode、updateEdge 和 deleteEdge) 的字首是保留的。

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
}

將變更套用至 GraphQL 結構描述

您可以修改 GraphQL 來源結構描述，然後再次執行公用程式，從 Neptune 資料庫取得最新的結構描述。每次公用程式在資料庫中發現新的結構描述時，就會產生新的 GraphQL 結構描述。

您也可以手動編輯 GraphQL 來源結構描述，並使用來源結構描述做為輸入，而不是 Neptune 資料庫端點，來重新執行公用程式。

最後，您可以使用以下 JSON 格式將變更放入檔案中：

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

例如：

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

然後，當您在命令中使用 --input-schema-changes-file 參數，在此檔案上執行公用程式時，公用程式會立即套用您的變更。