Ejecuta algoritmos de Spanner Graph

Vista previa — Algoritmos de Spanner Graph

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Esta función está disponible en las ediciones Enterprise y Enterprise Plus de Spanner. Para obtener más información, consulta la descripción general de las ediciones de Spanner.

NOTA: Si ejecutas algoritmos de grafos en una instancia de Spanner en la región us-east1, debes especificar uno de estos como zone en los parámetros de entrada del algoritmo: us-east1-b, us-east1-c o us-east1-d. Para todas las demás regiones, no es necesario especificar una zona.

En este documento, se explica cómo ejecutar algoritmos en Spanner Graph.

Estructura de la consulta del algoritmo de Spanner Graph

Una consulta de algoritmo de Spanner Graph tiene la siguiente estructura:

EXPORT DATA OPTIONS (<export_option_list>) AS
GRAPH graph_name
<match_clause>
<call_statement> algorithm_name(<common_input>, <algorithm_specific_input>)
  YIELD <algorithm_specific_output>
RETURN <results>

• <export_option_list>: Son las opciones que definen cómo persistir los resultados de la consulta del algoritmo. Consulta Opciones de Cloud Storage y Opciones de Spanner.

• graph_name: Es el nombre del gráfico.

• <match_clause>: Son instrucciones MATCH opcionales para definir los elementos de entrada del algoritmo.

• <call_statement>: Usa CALL cuando omitas <match_clause> y quieras operar en todo el gráfico. Usa CALL PER() cuando <match_clause> esté presente y quieras operar en la tabla de trabajo. Para obtener más información, consulta GQL CALL.

• algorithm_name: Es el nombre del algoritmo que se ejecutará. Para ver los algoritmos disponibles, consulta Algoritmos de Spanner Graph.

• <common_input>: Son los parámetros de entrada con nombre que son comunes a todas las consultas de algoritmos. Para obtener más información, consulta los parámetros de entrada comunes del algoritmo.

• <algorithm_specific_input>: Son los parámetros de entrada con nombre del algoritmo. Para obtener más información, consulta los parámetros de entrada definidos en Algoritmos de Spanner Graph.

• <algorithm_specific_output>: Es el resultado de la llamada al algoritmo. Para obtener más información, consulta los resultados definidos en los algoritmos de grafos de Spanner y YIELD en la sentencia CALL.

• <results>: Define qué se devolverá en los resultados de la búsqueda.

La consulta se compone de una instrucción EXPORT DATA, que define cómo persistir los resultados, y una CLÁUSULA GRAPH que produce el resultado de la consulta del algoritmo.

En su forma más simple, la cláusula de gráfico identifica el gráfico, CALL como un algoritmo que produce un resultado predefinido y, luego, especifica qué RETURN del resultado del algoritmo.

De manera opcional, la cláusula graph puede usar instrucciones MATCH compatibles para seleccionar elementos de interés. En este caso, usa una cláusula PER () para agrupar todas las filas que devuelve MATCH como entrada para el algoritmo. El algoritmo opera en un subgrafo lógico compuesto por el conjunto único de nodos y aristas seleccionados.

La consulta no devuelve ningún dato. Los resultados se conservan según export_option_list.

Para obtener más información sobre las consultas del algoritmo de Spanner Graph, consulta las siguientes secciones de este documento:

• Parámetros de entrada comunes del algoritmo
• Cómo controlar el resultado del algoritmo
• Ejecuta consultas de ejemplo del algoritmo

Parámetros de entrada comunes del algoritmo

Especifica estos parámetros de entrada con nombre en el siguiente formato: NAME => VALUE, ....

Nombre	Tipo de valor	Obligatorio	Valor predeterminado	Descripción
node_labels	ARRAY	No	(ninguno)	Solo se admite cuando se usa CALL. Es una lista de etiquetas de nodos que se incluirán en los datos de entrada del algoritmo. Si se especifica, solo se incluyen los nodos con al menos una etiqueta coincidente.
edge_labels	ARRAY	No	(ninguno)	Solo se admite cuando se usa CALL. Es una lista de etiquetas de borde que se incluirán en la entrada del algoritmo. Si se especifica, solo se incluyen las aristas con al menos una etiqueta coincidente.
edge_weight_property	STRING	No	(ninguno)	Nombre de la propiedad de borde que contiene los pesos. Si no se define, el sistema asigna un peso predeterminado de 1 a todas las aristas. El tipo de valor de la propiedad debe ser numérico.
machine_category	STRING	No	predeterminado	Es la categoría de máquina que se usará para la ejecución del algoritmo. Los valores admitidos son default y large.
zone	STRING	No	(ninguno)	Es la zona en la que se ejecuta el algoritmo. Debe ser una de las zonas de la región en la que se recibe la búsqueda.
max_idle_time	STRING	No	30 min	Especifica cuánto tiempo debe permanecer activa la instancia de procesamiento para su reutilización después de que se complete el algoritmo. El formato es una secuencia de números decimales, cada uno con un sufijo de unidad, como 4m, 1.5h o 1h45m. Las unidades de tiempo válidas son ns, us (o µs), ms, s, m y h.

Cómo controlar el resultado del algoritmo

Debes conservar los resultados de las consultas del algoritmo antes de poder inspeccionarlos. Usa export_data_option para describir cómo conservar los resultados. Puedes conservar los resultados en Cloud Storage o en la misma instancia de Spanner desde la que se originó la consulta.

Persiste los resultados en Cloud Storage

Para usar esta opción, asegúrate de que el rol de administrador de objetos de almacenamiento (roles/storage.objectAdmin) se otorgue a la cuenta de servicio de Spanner administrada por Google [e-mail].

Se admiten las siguientes opciones de EXPORT DATA cuando se persisten los resultados en Cloud Storage. Especifica las opciones en el siguiente formato: NAME=VALUE, ....

Nombre	Tipo de valor	Obligatorio	Descripción
uri	STRING	Sí	Es el URI de destino de la exportación, en formato gs://bucket/path/file. Si exportas una gran cantidad de datos, usa un comodín en uri para exportar los datos a varios archivos. Por ejemplo, gs://bucket/path/file_*.csv.
format	STRING	Sí	Es el formato de los datos exportados. Valores admitidos: CSV, PARQUET, AVRO.
header	BOOL	No	Si es true, el sistema imprime encabezados de columnas para la primera fila de cada archivo de datos. El valor predeterminado es false. Solo se aplica a CSV.
overwrite	BOOL	No	Si es true, el sistema reemplaza los archivos existentes con el mismo URI. De lo contrario, si existen archivos con el mismo URI, la instrucción devuelve un error. El valor predeterminado es false.
field_delimiter	STRING	No	Es el delimitador que separa los campos. Valor predeterminado: , (coma). Solo se aplica a CSV.
compression	STRING	No	Especifica el formato de compresión. Si no especificas un formato de compresión, los archivos permanecerán sin comprimir. Para CSV, el valor admitido es GZIP. Para PARQUET, los valores admitidos son SNAPPY, GZIP y ZSTD. Para AVRO, los valores admitidos son DEFLATE y SNAPPY.

Los nombres de las columnas en la cláusula RETURN definen los nombres de las columnas en los archivos de salida de Cloud Storage.

Exporta datos a uno o más archivos

Las consultas de Spanner Graph admiten un solo operador de comodín (*) en la uri. El comodín puede aparecer en el componente del nombre de archivo, pero no en el nombre del bucket, el nombre de la carpeta ni la extensión del archivo. Si el conjunto de resultados es grande, el uso del operador de comodín le indica a Spanner Graph que cree varios archivos fragmentados según el patrón que proporciones. El sistema reemplaza el operador de comodín por un número, comenzando en cero, con un relleno a la izquierda de 12 dígitos. Por ejemplo, un URI gs://my-bucket/file-*.csv crea archivos como gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv y archivos similares.

Si usas uri sin comodín, el resultado es un solo archivo, como gs://my-bucket/file.csv.

Tipos de datos

Cuando exportas datos, los tipos de datos de grafos de Spanner se convierten de la siguiente manera, según el formato:

CSV

Todos los tipos de datos se convierten a su representación de cadena:

• Los valores de BOOL se convierten en true o false.
• Los valores de BYTES se codifican en Base64.
• Los valores de TIMESTAMP tienen el formato YYYY-MM-DD HH:MM:SS.ffffff UTC.
• Los valores NULL aparecen como cadenas vacías.

No puedes exportar datos anidados y repetidos en formato CSV.

Avro

Tipo de datos de Spanner	Tipos de datos de Avro
BOOL	BOOLEAN
INT64	LONG
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	BYTES con el tipo lógico DECIMAL(38,9)
STRING	STRING
BYTES	BYTES
TIMESTAMP	LONG (microsegundos desde el ciclo de entrenamiento)
NULL	null

Parquet

Tipo de datos de Spanner	Tipo de datos de Parquet
BOOL	BOOLEAN
INT64	INT64
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	DECIMAL(38,9)
STRING	STRING
BYTES	BYTE_ARRAY
TIMESTAMP	TIMESTAMP_MICROS
NULL	null

Conserva los resultados en Spanner

Se admiten las siguientes opciones de EXPORT DATA cuando se conservan los resultados en tu instancia de Spanner de origen. Especifica las opciones en el siguiente formato: NAME=VALUE, ....

Nombre	Tipo de valor	Obligatorio	Descripción
format	STRING	Sí	Es el formato de los datos exportados. Debe ser CLOUD_SPANNER.
table	STRING	Sí	El nombre de la tabla de Spanner de destino en la que se escribirán los resultados. Puede ser cualquier tabla de la instancia de Spanner.
write_mode	STRING	Sí	Es el modo de escritura que se usará. Los valores admitidos son los siguientes: update_ignore_all: Actualiza las filas existentes en la tabla de destino. upsert_ignore_all: Inserta filas nuevas o actualiza las existentes en la tabla de destino. En ambos modos, Spanner omite cualquier registro que genere un incumplimiento de restricción (por ejemplo, claves faltantes en una actualización, incumplimiento de índice único, incumplimiento de restricción de clave externa). Sin embargo, la escritura falla para los errores que no son de incumplimiento de restricciones (por ejemplo, no coinciden los tipos de columna o faltan valores para las columnas NOT NULL).

Requisitos

Cuando conservas los resultados del algoritmo en Spanner, la consulta del algoritmo debe satisfacer lo siguiente:

• La tabla de destino debe existir.
• Las columnas deben existir con un tipo coincidente: Todos los nombres de columna especificados en la cláusula RETURN ya deben existir en la tabla de destino con un tipo de datos coincidente. Si es necesario, usa alias para que coincidan con los nombres de las columnas de la tabla de destino. Ejemplo: RETURN node.id AS person_id.
• Incluye todas las columnas de clave primaria: La cláusula RETURN debe incluir todas las columnas de clave primaria de la tabla de destino.

Semántica de escritura

La persistencia de los resultados en Spanner es una operación no transaccional. Proporciona atomicidad a nivel de la fila. Esto significa que el sistema escribe correctamente todas las columnas de la misma fila o no escribe ninguna de ellas. Sigue la semántica de al menos una vez. Esto significa que una fila se puede escribir varias veces. La lectura de la tabla de destino mientras se ejecuta el proceso puede generar resultados incompletos.

Si falla la ejecución general, el sistema no revierte los cambios que ya se hayan confirmado. El proceso de escritura falla en el primer error no reintentable. Cuando se produce un error de escritura, el ERROR_MESSAGE en GRAPH_OPERATION_EXECUTION_STATUS indica la clave primaria de la fila que falló junto con el motivo específico del error.

El sistema vuelve a escribir los resultados del algoritmo en Spanner Graph con la prioridad MEDIUM.

Ejecuta consultas de ejemplo del algoritmo

En esta sección, se muestran ejemplos de consultas del algoritmo de Spanner Graph que puedes ejecutar en una instancia de prueba. Para obtener una lista completa de los algoritmos que admite Spanner Graph, consulta Algoritmos de Spanner Graph.

Antes de comenzar

Para ejecutar las consultas de ejemplo del algoritmo de Spanner Graph, primero debes completar los siguientes pasos:

1. Sigue los pasos de Configurar y consultar Spanner Graph para crear un gráfico de Spanner.
2. Asegúrate de tener los permisos necesarios.
3. Opcional: Aumenta el esquema del Spanner Graph si conservas el resultado en Spanner.

Agrega una columna nueva llamada page_rank a la tabla Account. Spanner escribe los resultados del algoritmo en esta columna nueva. Luego, actualiza la definición del gráfico para que puedas acceder a page_rank como una propiedad del nodo.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

Ejecuta el algoritmo en el gráfico completo con el filtro de etiquetas y persiste los resultados en Cloud Storage

En este ejemplo, se ejecuta PageRank para clasificar los Account en función de los Transactions en los que participan y se conservan los resultados en un archivo de Cloud Storage en formato CSV como "my-bucket-name/my-output.csv".

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

En Cloud Storage, deberías ver un archivo CSV con dos columnas (id y page_rank) cuando esta consulta se complete correctamente.

Ejecuta el algoritmo en el subgrafo definido por MATCH y persiste los resultados en el gráfico.

En este ejemplo, se usa el patrón MATCH para hacer coincidir de forma dinámica un subgrafo lógico que contiene todos los nodos Account y solo las aristas Transfer con un importe inferior a 500. Este subgrafo lógico es la entrada del algoritmo PageRank. Spanner conserva los resultados del algoritmo en la tabla Account.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

Una vez que la consulta se complete correctamente, ejecuta la siguiente consulta:

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

Deberías ver resultados similares a los siguientes:

id	page_rank
20	0.49
16	0.46
7	0.05

Verifica el estado de ejecución del algoritmo

Cuando una consulta de algoritmo de grafos se completa correctamente, muestra cero filas y el estado Success. Según el tamaño del grafo de entrada y las configuraciones específicas del algoritmo, la ejecución del algoritmo puede tardar un tiempo en completarse. Puedes verificar el progreso y el estado de ejecución de una consulta de algoritmo de grafo en la tabla SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS. Esta tabla conserva la información durante 30 días.

GRAPH_OPERATION_EXECUTION_STATUS esquema

Nombre de la columna	Tipo	Descripción
QUERY_ID	STRING	Es el ID de la consulta del algoritmo de grafos.
QUERY_TEXT	STRING	El texto de la declaración de consulta.
START_TIMESTAMP	TIMESTAMP	Es la fecha y hora en que comenzó la ejecución de la búsqueda.
LAST_UPDATE_TIMESTAMP	TIMESTAMP	Fecha y hora en la que se actualizó el estado por última vez.
PROGRESS	FLOAT	Porcentaje de finalización estimado. El valor está entre 0 y 1, donde 0 significa que se inició y 1 significa que se completó.
STATUS	STRING	Es el estado actual de la ejecución. Los valores posibles son PENDING, IN_PROGRESS, OK, CANCELLED, DEADLINE_EXCEEDED y UNKNOWN.
ERROR_MESSAGE	STRING	Es el mensaje de error si falló la ejecución de la consulta.

La siguiente consulta de ejemplo enumera las consultas de gráficos que aún no se completaron correctamente:

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

Cómo cancelar la ejecución del algoritmo

Para cancelar una consulta de algoritmo de grafo en curso, ubica el query_id en la tabla SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS y, luego, llama a cancel_query para ese query_id.

¿Qué sigue?

• Catálogo de algoritmos de Spanner Graph.
• Requisitos del esquema del algoritmo de Spanner Graph y compatibilidad de funciones.

• Prácticas recomendadas para el algoritmo de Spanner Graph.