Exportación de resultados de consultas de Gremlin a Amazon S3 - Amazon Neptune
EjemplosRequisitos previosFormato de respuesta

Exportación de resultados de consultas de Gremlin a Amazon S3

A partir de la versión 1.4.3.0 del motor, Amazon Neptune admite la exportación de resultados de consultas de Gremlin directamente a Amazon S3. Esta característica le permite gestionar resultados de consultas de gran tamaño de forma eficiente al exportarlos a un bucket de Amazon S3 en lugar de devolverlos como respuesta a la consulta.

Para exportar los resultados de la consulta a Amazon S3, utilice el paso call() con el nombre de servicio neptune.query.exportToS3 como último paso de la consulta de Gremlin. El paso del terminal en Tinkerpop drivers using Bytecode se puede añadir después del paso call(). Los parámetros de exportación deben proporcionarse como valores de cadena.

nota

La consulta que incluya el paso call() con neptune.query.exportToS3 producirá un error si no se utiliza como paso final. Los clientes de Gremlin que utilizan bytecode pueden usar los pasos del terminal. Consulte las prácticas recomendadas de Gremlin en la documentación de Amazon Neptune para obtener más información. 

g.V()
  ...
  .call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'kmskeyArn': 'optional-kms-key-arn'
  ])
Parámetros

  • destination: (obligatorio) el URI de Amazon S3 en el que se escribirán los resultados.

  • format: (obligatorio) el formato de salida, actualmente solo admite “GraphSONv3”.

  • keyArn: (opcional) el ARN de una clave de AWS KMS para el cifrado del servidor de Amazon S3.

Ejemplos

Consulta de ejemplo 

g.V().
    hasLabel('Comment').
    valueMap().
    call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'keyArn': 'optional-kms-key-arn'
  ])

Ejemplo de respuesta a una consulta 

{
    "destination":"s3://your-bucket/path/result.json,
    "exportedResults": 100,
    "exportedBytes": 102400
}

Requisitos previos

  • La instancia de base de datos de Neptune debe tener acceso a Amazon S3 a través de un punto de conexión de VPC de tipo puerta de enlace.

  • Para usar el cifrado de AWS KMS personalizado en la consulta, se requiere un punto de conexión de VPC de tipo interfaz para AWS KMS que permita a Neptune comunicarse con AWS KMS.

  • Debe habilitar la autenticación de IAM en Neptune y disponer de los permisos de IAM adecuados para escribir en el bucket de Amazon S3 de destino. De lo contrario, se producirá un error 400 de solicitud incorrecta “Cluster must have IAM authentication enabled for S3 Export”.

  • El bucket de Amazon S3 de destino:

    • El bucket de Amazon S3 de destino no debe ser público. Debe habilitarse Block public access.

    • El destino de Amazon S3 de destino no debe estar vacío.

    • El bucket de Amazon S3 de destino debe tener una regla de ciclo de vida en Delete expired object delete markers or incomplete multipart uploads con Delete incomplete multipart uploads. Consulte Amazon S3 lifecycle management update - support for multipart uploads and delete markers para obtener más información.

      Imagen que muestra las acciones de la regla del ciclo de vida.

    • El bucket de Amazon S3 de destino debe tener una regla de ciclo de vida en Delete expired object delete markers or incomplete multipart uploads con Delete incomplete multipart uploads establecido en un valor superior al que tardará la evaluación de la consulta (por ejemplo, 7 días). Esto es necesario para eliminar las cargas incompletas (que no son directamente visibles, pero que generarían costos) en caso de que Neptune no pueda completarlas o abortarlas (por ejemplo, debido a fallos de la instancia o del motor). Consulte Amazon S3 lifecycle management update - support for multipart uploads and delete markers para obtener más información.

      Imagen que muestra las acciones de la regla del ciclo de vida y los marcadores de eliminación de objetos caducados.
Consideraciones importantes

  • El paso de exportación debe ser el último paso de la consulta de Gremlin.

  • Si ya existe un objeto en la ubicación de Amazon S3 especificada, la consulta producirá un error.

  • El tiempo máximo de ejecución de las consultas de exportación está limitado a 11 horas y 50 minutos. Esta característica utiliza Sesiones de acceso directo. Actualmente está limitado a 11 horas y 50 minutos para evitar problemas de caducidad de tokens.

    nota

    La consulta de exportación sigue respetando el tiempo de espera de la consulta. Para exportaciones de gran tamaño, se debe utilizar un tiempo de espera de consulta adecuado.

  • Todas las nuevas cargas de objetos en Amazon S3 se cifran automáticamente.

  • Para evitar los costos de almacenamiento derivados de cargas de varias partes incompletas provocadas por errores o bloqueos, recomendamos configurar una regla de ciclo de vida con Delete incomplete multipart uploads en el bucket de Amazon S3.

Formato de respuesta

En lugar de devolver directamente los resultados de la consulta, esta devuelve metadatos sobre la operación de exportación, incluidos el estado y los detalles de la exportación. Los resultados de la consulta en Amazon S3 estarán en formato GraphSONv3. 

{
  "data": {
    "@type": "g:List",
    "@value": [
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Safari"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 7
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "192.0.2.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348341961000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "no way!"
            ]
          }
        ]
      },
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Firefox"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 2
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "203.0.113.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348352960000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "ok"
            ]
          }
        ]
      },
      
      
      ...
      
      
    ]
  }
}
Seguridad

  • Todos los datos transferidos a Amazon S3 se cifran en tránsito mediante SSL.

  • Puede especificar una clave de AWS KMS para el cifrado en el servidor de los datos exportados. Amazon S3 cifra los datos nuevos de forma predeterminada. Si el bucket está configurado para utilizar una clave de AWS KMS específica, se utilizará dicha clave.

  • Neptune verifica que el bucket de destino no sea público antes de iniciar la exportación.

  • No se admiten las exportaciones entre cuentas ni entre regiones.

Gestión de errores

  • El bucket de Amazon S3 de destino es público.

  • El objeto especificado ya existe.

  • No tiene permisos suficientes para escribir en el bucket de Amazon S3.

  • La ejecución de la consulta supera el límite de tiempo máximo.

Prácticas recomendadas

  • Utilice las reglas del ciclo de vida de los buckets de Amazon S3 para eliminar las cargas de varias partes incompletas.

  • Supervise sus operaciones de exportación mediante los registros y las métricas de Neptune. Puede comprobar el punto de conexión de estado de Gremlin para ver si hay alguna consulta en ejecución actualmente. Mientras el cliente no reciba una respuesta, se considerará que la consulta está en ejecución.