Expresiones, predicados y funciones de GQL

En este artículo se proporciona una referencia completa para expresiones GQL, predicados y funciones integradas disponibles en el grafo en consultas de Microsoft Fabric. Use esta referencia para comprender cómo realizar cálculos, filtrar resultados y transformar datos en las consultas de grafos.

Para obtener información general sobre el lenguaje de consulta GQL y ejemplos de consultas de un extremo a otro, consulte la guía del lenguaje GQL. Para obtener información sobre los tipos de datos admitidos y la sintaxis literal, vea Valores de GQL y tipos de valor.

Literals

Los literales son expresiones simples que se evalúan directamente con el valor indicado. En el artículo Valores y tipos de valor de GQL se explican los literales de cada tipo de valor en detalle.

Example:

1
1.0d
1.00m
TRUE
"Hello, graph!"
[ 1, 2, 3 ]
NULL

Para obtener una sintaxis literal detallada para cada tipo de datos, consulte Valores de GQL y tipos de valor.

Predicates

Los predicados son expresiones booleanas que normalmente se usan para filtrar los resultados en las consultas GQL. Se evalúan como TRUE, FALSEo UNKNOWN (null).

Precaución

Cuando se usan predicados como filtro, solo conservan los elementos para los que el predicado se evalúa como TRUE.

Predicados de comparación

Use estos operadores para comparar valores:

  • = (igual)
  • <> (no igual)
  • < (menor que)
  • > (mayor que)
  • <= (menor o igual que)
  • >= (mayor o igual que)

GQL usa lógica de tres valores donde las comparaciones con valor NULL devuelven UNKNOWN:

Expression Resultado
5 = 5 TRUE
5 = 3 FALSE
5 = NULL UNKNOWN
NULL = NULL UNKNOWN

Para obtener un comportamiento de comparación específico, consulte la documentación de cada tipo de valor en los valores de GQL y los tipos de valor.

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915
RETURN p.firstName

Si ambos operandos son números, GQL los compara por sus valores numéricos.

Importante

Graph aún no soporta todas las comparaciones numéricas que define GQL. El comportamiento actual utiliza estas reglas:

  • Una comparación entre un entero y un número aproximado convierte el entero en un tipo numérico aproximado.
  • Una comparación entre valores enteros con signo y sin signo generalmente convierte ambos valores en un tipo entero con signo. Un valor sin signo fuera del rango de enteros con signo causa un error.

Expresiones lógicas

Combinar condiciones con operadores lógicos:

  • AND (ambas condiciones son verdaderas)
  • OR (cualquiera de las condiciones true)
  • NOT (nega la condición)
  • XOR (disjunción exclusiva— true cuando exactamente un operando es true)

Example:

MATCH (p:Person)
FILTER WHERE p.birthday <= 20050915 AND p.firstName = 'John'
RETURN p.firstName || ' ' || p.lastName AS fullName

Predicados de existencia de propiedades

Para comprobar si existen propiedades, use estos predicados:

p.locationIP IS NOT NULL
p.browserUsed IS NULL

Nota:

Intentar acceder a una propiedad conocida como inexistente resulta en un error de sintaxis. El acceso a una propiedad potencialmente inexistente se evalúa a null. La determinación de si una propiedad es conocida o potencialmente no existente se basa en el tipo del nodo o borde al que se tiene acceso.

Subconsultas de existencia

Utiliza una subconsulta de formulario EXISTS de procedimiento para comprobar si una consulta anidada devuelve al menos una fila:

EXISTS {
  <query statements>
  RETURN <columns>
}

El resultado es un valor booleano no nulo:

  • TRUE si la subconsulta devuelve una o más filas.
  • FALSE si la subconsulta no devuelve filas.

Las variables ya en el alcance están implícitamente disponibles dentro de la subconsulta. Las variables introducidas solo dentro de la subconsulta no están disponibles fuera de ella.

Úsalo EXISTS en un filtro:

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:knows]->(friend:Person)
  RETURN friend
}
RETURN p.firstName, p.lastName

Úsase NOT EXISTS para conservar filas para las que la subconsulta no devuelve filas. También puedes usar EXISTS en LET, RETURN, ORDER BY, y agregar expresiones de filtro o fuente. EXISTS no está soportado dentro de un filtro de predicados de lista.

Importante

No se soportan formas solo de patrones de grafo como EXISTS { (p)-[:knows]->(friend) } y EXISTS ((p)-[:knows]->(friend)) Graph. Utiliza el formulario de procedimiento mostrado en los ejemplos anteriores. No se soportan subconsultas escalares VALUE { ... } .

Precaución

EXISTS prueba si la subconsulta devuelve una fila, no si un valor agregado es distinto de cero. Un agregado no agrupado como RETURN count(*) devuelve una fila incluso cuando MATCH no encuentra filas, de modo que esa forma de EXISTS evalúa a TRUE. Devuelve una variable emparejada cuando quieras comprobar si existen coincidencias.

Para más información sobre subconsultas correlacionadas, consulte la CALL afirmación en la guía del lenguaje GQL.

Enumerar predicados de pertenencia

Pruebe si los valores están en listas:

p.firstName IN ['Alice', 'Bob', 'Charlie']
p.gender NOT IN ['male', 'female']

Funciones predicadas de lista

Utiliza una función predicado de lista para evaluar una expresión booleana para los elementos de una lista:

ALL(element IN list WHERE predicate)
ANY(element IN list WHERE predicate)
NONE(element IN list WHERE predicate)
SINGLE(element IN list WHERE predicate)

La fuente puede ser un literal de lista, una propiedad de valor de lista, una variable o una lista de grupo de un patrón de longitud variable.

Las funciones tienen los siguientes significados:

Function Meaning
ALL Cada elemento satisface el predicado.
ANY Al menos un elemento satisface el predicado.
NONE Ningún elemento satisface el predicado.
SINGLE Exactamente un elemento satisface el predicado.

El siguiente ejemplo evalúa las cuatro funciones sobre una lista construida dinámicamente:

LET items = [1, 2, 3]
RETURN ALL(x IN items WHERE x > 0) AS all_match,
       ANY(x IN items WHERE x = 2) AS any_match,
       NONE(x IN items WHERE x < 0) AS none_match,
       SINGLE(x IN items WHERE x = 2) AS single_match

Los cuatro valores devueltos son TRUE.

También puedes evaluar propiedades de los elementos a partir de una lista. En este ejemplo, connections es la lista de grupos creada por el patrón de aristas de longitud variable:

MATCH (person:Person)-[connections:knows]->{1,4}(friend:Person)
WHERE ALL(connection IN connections WHERE connection.creationDate IS NOT NULL)
RETURN person.firstName, friend.firstName

Los predicados de lista utilizan lógica de tres valores. La tabla describe el resultado en términos de los valores producidos por la expresión de filtro para los elementos de la lista:

Function TRUE FALSE UNKNOWN Lista vacía
ALL Todo resultado de filtro es TRUE. Al menos un resultado es FALSE. Ningún resultado es FALSE, y al menos uno es UNKNOWN. TRUE
ANY Al menos un resultado de filtro es TRUE. Ningún resultado es TRUE ni UNKNOWN. Ningún resultado es TRUE, y al menos uno es UNKNOWN. FALSE
NONE Ningún resultado es TRUE ni UNKNOWN. Al menos un resultado es TRUE. Ningún resultado es TRUE, y al menos uno es UNKNOWN. TRUE
SINGLE Exactamente un resultado es TRUE, y ninguno es UNKNOWN. Más de un resultado es TRUE, o ningún resultado es TRUE o UNKNOWN. Como mucho, un resultado es TRUE, y al menos uno es UNKNOWN. FALSE

Si la lista de fuentes es nula, cada función devuelve UNKNOWN. Un elemento de lista nulo contribuye al resultado de evaluar el filtro con ese elemento vinculado a nulo; no hace automáticamente que el resultado de la función sea desconocido.

La variable elemento está disponible solo dentro de la expresión de filtro del predicado de lista. El filtro también puede referenciar variables de la consulta adjunta. Si la variable elemento tiene el mismo nombre que una variable externa, la variable local de elemento tiene prioridad. Los predicados de lista anidada pueden sombrear de forma similar una variable de elemento externo.

Las funciones agregadas pueden referenciar una lista de grupos que encierra, pero no pueden agregar la variable de elemento localmente acotada. EXISTS Las subconsultas tampoco están soportadas dentro de un filtro de predicado de lista.

ANY(...) es una función predicado de lista. No lo confundas con el ANY SHORTEST prefijo de búsqueda de caminos ni con el ANY tipo de valor dinámico.

Predicados de patrón de cadena

Coincidencia de cadenas mediante técnicas de coincidencia de patrones:

p.firstName CONTAINS 'John'
p.browserUsed STARTS WITH 'Chrome'
p.locationIP ENDS WITH '.1'

Para la coincidencia de expresiones regulares de RE2, usa MSFT.REGEXP_LIKE.

Expresiones aritméticas

Use operadores aritméticos estándar con valores numéricos:

  • + (adición)
  • - (resta)
  • * (multiplicación)
  • / (división)

Los operadores aritméticos siguen las convenciones matemáticas generales.

Precedencia:

Por lo general, los operadores siguen las reglas de precedencia de operador establecidas, como * antes +de . Use paréntesis para controlar el orden de evaluación según sea necesario.

Example:

(p.birthday < 20050915 OR p.birthday > 19651231) AND p.gender = 'male'

Reglas de coerción:

Use las siguientes reglas en orden de prioridad:

  1. Las expresiones aritméticas que implican un tipo numérico aproximado devuelven un tipo numérico aproximado.
  2. Las expresiones aritméticas que involucran tanto tipos enteros con signo como no signados devolven un tipo entero con signo.

Property Access

Acceda a las propiedades mediante la notación de puntos:

p.firstName
edge.creationDate

Acceso a la lista

Obtener acceso a los elementos de lista mediante la indexación basada en cero:

interests[0]    -- first element
interests[1]    -- second element

Funciones integradas

GQL admite varias funciones integradas para el procesamiento y el análisis de datos.

Funciones numéricas

Utiliza funciones numéricas para transformar valores numéricos, calcular valores trigonométricos y crear rangos enteros.

Valor absoluto y poder

Function Description
ABS(value) Devuelve el valor absoluto. El resultado tiene el mismo tipo numérico que value.
POWER(base, exponent) Sube base a exponent y devuelve un DOUBLE.

Ambas funciones aceptan valores numéricos. Un argumento nulo produce nulo. Una operación numérica inválida, como un resultado desbordado POWER , produce un error.

RETURN ABS(-1) AS absoluteValue, POWER(2, -2) AS reciprocalSquare

El resultado es el siguiente:

Valor absoluto reciprocalSquare
1 0.25

Funciones trigonométricas

Las funciones trigonométricas aceptan un valor numérico y devuelven un DOUBLE. Un argumento nulo produce nulo.

Function Description
SIN(value), COS(value), , TAN(value), COT(value) Calcula una función trigonométrica. value es un ángulo en radianes.
ASIN(value), ACOS(value), ATAN(value) Calcula una función trigonométrica inversa. El resultado está en radianes. ASIN y ACOS requieren un valor de -1 a través 1de .
SINH(value), COSH(value), TANH(value) Calcula una función hiperbólica.
DEGREES(value) Convierte un ángulo de radianes a grados.
RADIANS(value) Convierte un ángulo de grados a radianes.

Un argumento fuera del dominio matemático de una función produce un error.

RETURN COS(0) AS cosine, RADIANS(180) AS angle

El resultado es el siguiente:

Coseno ángulo
1.0 3.141592653589793238462643383279502884

Rangos enteros

RANGE(start, end) devuelve una lista de enteros desde start hacia end, usando un paso de 1. RANGE(start, end, step) utiliza el paso no cero especificado. start, end, y step deben ser enteros no nulos. Cero es válido para start o end; solo step debe ser distinto de cero.

El rango incluye start. Solo incluye end cuando se añaden step exactamente los tramos end repetidamente. Un paso positivo con start mayor que end, o un paso negativo con start menor que end, devuelve una lista vacía. Un paso cero produce un error.

RETURN RANGE(0, 10, 3) AS ascending, RANGE(5, 0, -2) AS descending

El resultado es el siguiente:

ascendente descendente
[0, 3, 6, 9] [5, 3, 1]

Si todos los argumentos son enteros sin signo, RANGE devuelve un LIST<UINT64>. De lo contrario, devuelve a LIST<INT64> y rechaza valores que no pueden representarse de forma segura como enteros con signo.

Funciones agregadas

Las funciones agregadas combinan valores ya sea entre filas de entrada o dentro de una lista de grupos limitada por un patrón de longitud variable.

Function Description
COUNT(*) Cuenta las filas de entrada, incluidas las filas que contienen valores nulos.
COUNT(expression) Cuenta los resultados no nulos de expression.
SUM(expression) Devuelve la suma de valores numéricos no nulos.
AVG(expression) Devuelve la media de los valores numéricos no nulos.
MIN(expression) Devuelve el valor mínimo no nulo.
MAX(expression) Devuelve el valor máximo no nulo.
COLLECT_LIST(expression) Devuelve una lista con un elemento para cada entrada, incluyendo elementos nulos.
COLLECT_ONE(expression) Devuelve un valor de entrada no nulo. El valor seleccionado no es determinista.
COLLECT_ELEMENTS(expression) Concatena los elementos de las entradas con valores de lista en una sola lista. Las listas de entrada nulas no aportan elementos, pero los elementos nulos dentro de una lista permanecen en el resultado.

Cuando una consulta agregada no tiene columnas de agrupación y no recibe filas de entrada, COUNT devuelve 0, COLLECT_LIST y COLLECT_ELEMENTS devuelve una lista vacía, y las demás funciones agregadas devolven nulo. No te fíes del orden de valores devueltos por un agregado de colección. Con agrupar columnas, ninguna fila de entrada produce grupo y, por tanto, no produce fila de resultado.

Cuantificadores de conjuntos

Úsalos ALL para incluir valores duplicados o DISTINCT para eliminarlos. ALL es el valor predeterminado para los agregados de expresión. COUNT(*) no acepta un cuantificador conjunto.

MATCH (person:Person)
RETURN COUNT(person) AS personCount,
       COUNT(DISTINCT person.browserUsed) AS browserCount

Para COLLECT_LIST, DISTINCT elimina valores duplicados y conserva como máximo un nulo. Para COLLECT_ELEMENTS, DISTINCT se aplica a los elementos después de que las listas de entrada se concatenan. DISTINCT no hace COLLECT_ONE que sea determinista.

Filtros y límites específicos de agregados

Sumar FILTER (WHERE predicate) después de un agregado para incluir solo los valores de que predicate es cierto. Se excluyen los resultados falsos y de predicados desconocidos. Este filtro afecta solo a ese agregado, no a las filas de entrada disponibles para otras expresiones en la misma RETURN.

Añade LIMIT n dentro del filtro agregado para considerar como máximo n las filas de entrada que califican. El filtrado ocurre antes del límite específico del agregado y DISTINCT se aplica después del límite.

MATCH (person:Person)
RETURN COUNT(*) AS allPeople,
       COUNT(*) FILTER (WHERE person.birthday < 19900101 LIMIT 5) AS sampleBornBefore1990

Agregación entre filas

Un agregado normalmente combina valores verticalmente entre las filas de entrada. Úsalo GROUP BY para calcular un resultado para cada grupo.

MATCH (p:Person)
RETURN count(*) AS total_people, avg(p.birthday) AS average_birth_year
MATCH (p:Person)-[:isLocatedIn]->(c:City)
RETURN c.id AS cityId, c.name, count(*) AS population, avg(p.birthday) AS average_birth_year
GROUP BY cityId, c.name

No coloques un agregado vertical directamente dentro de otro en el mismo bloque de consulta. Por ejemplo, SUM(COUNT(*)) no es válido. Utilízalo NEXT para separar los pasos de agregación cuando necesites agregar un resultado agregado.

Agregación dentro de un camino emparejado

Una variable de arista limitada por un patrón de longitud variable se convierte en una lista de grupos. Un agregado sobre esa variable es horizontal: calcula un resultado dentro de la lista para cada camino coincidido en lugar de combinar diferentes filas de entrada.

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN COUNT(knows) AS pathLength

Aquí, COUNT(knows) devuelve el número de aristas en cada camino emparejado. Las formas horizontales de COUNT, SUM, AVG, MIN, MAX, COLLECT_LIST, COLLECT_ONE, y COLLECT_ELEMENTS están soportadas. COUNT(*) y que sean formas específicas FILTER de agregados o LIMIT no horizontales.

Un agregado horizontal puede ser la entrada de un agregado vertical exterior:

MATCH (person:Person)-[knows:knows]->{1,5}(friend:Person)
RETURN MIN(COUNT(knows)) AS shortestMatchedPath

En esta consulta, COUNT(knows) calcula una longitud por cada camino emparejado y MIN combina esas longitudes a lo largo de las filas de entrada.

Para ejemplos orientados a tareas, véase Filtrar y agregar datos de grafos.

Expresiones condicionales

Utiliza una expresión sencilla CASE para comparar una expresión con uno o más valores y devuelve el resultado asociado al primer valor igual:

CASE expression
  WHEN value1 THEN result1
  WHEN value2 THEN result2
  ELSE default_result
END

NULLIF:

NULLIF(a, b) devuelve NULL si a es igual a b; de lo contrario, devuelve a.

Example:

MATCH (p:Person)
RETURN p.firstName,
       CASE p.gender
         WHEN 'male' THEN 'M'
         WHEN 'female' THEN 'F'
         ELSE 'Other'
       END AS gender_code,
       NULLIF(p.browserUsed, 'Unknown') AS browser

No se admiten expresiones buscadas CASE WHEN <predicate> . Para enrutar filas por predicados y ejecutar una sentencia de consulta o procedimiento anidado para la rama seleccionada, utiliza una WHEN sentencia condicional.

Funciones de cadena

Utiliza funciones de cadena para medir, transformar, buscar, comparar y combinar cadenas de caracteres.

Longitud del carácter y caso

Utiliza estas funciones para medir o cambiar cadenas de caracteres:

Function Description
CHAR_LENGTH(string) Devuelve el número de caracteres.
UPPER(string) Aplica mapeo de mayúsculas Unicode.
LOWER(string) Aplica mapeo en minúsculas Unicode.
CASEFOLD(string) Aplica el plegado de mayúsculas Unicode independiente de la localidad para emparejamiento sin mayúsculas.

Los mapeos Unicode pueden cambiar la longitud o la representación de una cadena:

RETURN UPPER('straße') AS uppercase,
       LOWER('İ') AS lowercase,
       CASEFOLD('Straße') AS folded

Los resultados son STRASSE, i̇, y strasse, respectivamente. CASEFOLD no es equivalente a LOWER. Por ejemplo, el plegado de casos mapea ß a ss y mapea las formas Σsigma griegas , σ, y ς a σ.

Normalizar cadenas

GQL define cuatro formularios de normalización Unicode:

  • Forma de normalización C (NFC), composición canónica.
  • Forma de normalización D (NFD), descomposición canónica.
  • Forma de normalización KC (NFKC), composición de compatibilidad.
  • Forma de normalización KD (NFKD), descomposición de compatibilidad.

NORMALIZE(string) por defecto es NFC. Especifique una forma de normalización como segundo argumento:

RETURN NORMALIZE('cafe\u0301') AS composed,
       NORMALIZE('café', NFD) AS decomposed

El argumento debe ser una cuerda.

Importante

Actualmente, Graph soporta NFC y NFD. Especificar NFKC o NFKD produce un error.

Cuerdas de recorte

Úsase TRIM para eliminar caracteres de espacio o un carácter especificado de ambos extremos, el principio o el final de una cadena:

RETURN TRIM('  text  ') AS both_ends,
       TRIM(BOTH FROM '  text  ') AS explicit_both,
       TRIM(LEADING FROM '  text  ') AS beginning,
       TRIM(TRAILING FROM '  text  ') AS ending,
       TRIM(LEADING 'f' FROM 'foobar') AS custom_character

El valor de trim personalizado debe ser exactamente un byte. Los caracteres Unicode de varios bytes y las cadenas que contienen varios caracteres no están soportados como valores de trim personalizados. Una fuente nula o un valor de trim personalizado devuelve null.

Cuerdas de unión

STRING_JOIN(list [, delimiter]) se une a una lista de cuerdas. El delimitador por defecto es una coma seguida de un espacio:

RETURN STRING_JOIN(['foo', 'bar', 'baz']) AS default_delimiter,
       STRING_JOIN(['foo', 'bar', 'baz'], '-') AS custom_delimiter

Los resultados son foo, bar, baz y foo-bar-baz. Una lista vacía devuelve una cadena vacía. Una lista nula, delimitador nulo o elemento de lista nula devuelve nulo. Todo elemento de lista no nulo debe ser una cadena.

Funciones de expresión regular

Graph proporciona estas funciones de expresión regular como extensiones de GQL:

Function Use
MSFT.REGEXP_LIKE Verifica si el texto contiene una coincidencia.
MSFT.REGEXP_COUNT Cuenta las coincidencias.
MSFT.REGEXP_INSTR Encuentra la posición de un grupo de coincidencia o captura.
MSFT.REGEXP_SUBSTR Devuelve el texto de una partida o grupo de captura.
MSFT.REGEXP_REPLACE Sustituye el texto correspondiente.
MSFT.REGEXP_LIKE

Regresa TRUE cuando el patrón coincide con cualquier parte de la cadena fuente. Si se encuentra ninguna coincidencia, devuelve FALSE.

Argumentos Syntax
2 MSFT.REGEXP_LIKE(source, pattern)
3 MSFT.REGEXP_LIKE(source, pattern, flags)

source es la cadena para buscar. pattern se empareja con cualquier subcadena de source a menos que la expresión en sí utilice anclajes como ^ o $. flags cambia el comportamiento de emparejamiento tal como se describe en las reglas y opciones de emparejamiento.

RETURN MSFT.REGEXP_LIKE('HELLO', 'hello', 'i') AS matches

El resultado es TRUE.

MSFT.REGEXP_COUNT

Devuelve el número de coincidencias. Si se encuentra ninguna coincidencia, devuelve 0.

Argumentos Syntax
2 MSFT.REGEXP_COUNT(source, pattern)
3 MSFT.REGEXP_COUNT(source, pattern, start)
4 MSFT.REGEXP_COUNT(source, pattern, start, flags)

source es la cadena a buscar e pattern identifica las coincidencias a contar. start es la posición de punto de código Unicode basada en ceros en la que puede comenzar la coincidencia. Un combate debe comenzar en o después de esta posición. La posición no se convierte en un nuevo comienzo de la cuerda para patrones anclados. flags cambia el comportamiento de emparejamiento tal como se describe en las reglas y opciones de emparejamiento.

RETURN MSFT.REGEXP_COUNT('1a2a3a4', '[0-9]', 3) AS match_count

La búsqueda comienza en la posición 3, la segunda a, así que solo se cuentan los dígitos 3 y 4 . El resultado es 2.

MSFT.REGEXP_INSTR

Devuelve la posición en base a cero de un grupo seleccionado de coincidencia o captura.

Argumentos Syntax
2 MSFT.REGEXP_INSTR(source, pattern)
3 MSFT.REGEXP_INSTR(source, pattern, start)
4 MSFT.REGEXP_INSTR(source, pattern, start, occurrence)
5 MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option)
6 MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option, flags)
7 MSFT.REGEXP_INSTR(source, pattern, start, occurrence, return_option, flags, group)

source es la cadena a buscar e pattern identifica las coincidencias. start es la posición de punto de código Unicode basada en ceros en la que puede comenzar la coincidencia. Un partido debe comenzar en o después de esta posición, lo que no supone un nuevo comienzo de la cuerda para patrones anclados.

occurrence selecciona la primera, segunda o posterior coincidencia no superpuesta encontrada entre start. group selecciona qué localizar dentro de esa coincidencia: 0 selecciona la coincidencia completa, y un valor positivo selecciona ese grupo de captura numerado. return_option determina qué límite de la coincidencia o grupo seleccionado se devuelve: 0 devuelve su posición inicial y 1 devuelve la posición inmediatamente después de su final. flags cambia el comportamiento de emparejamiento tal como se describe en las reglas y opciones de emparejamiento.

Si no se encuentra ninguna ocurrencia coincidente, o el grupo de captura seleccionado no participa en esa ocurrencia, la función devuelve -1.

RETURN MSFT.REGEXP_INSTR('banana', 'a', 0, 2) AS match_position

La segunda partida comienza en la posición 3, por lo que el resultado es 3.

MSFT.REGEXP_SUBSTR

Devuelve el texto de una coincidencia o grupo de captura seleccionado.

Argumentos Syntax
2 MSFT.REGEXP_SUBSTR(source, pattern)
3 MSFT.REGEXP_SUBSTR(source, pattern, start)
4 MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence)
5 MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence, flags)
6 MSFT.REGEXP_SUBSTR(source, pattern, start, occurrence, flags, group)

source es la cadena a buscar e pattern identifica las coincidencias. start es la posición de punto de código Unicode basada en ceros en la que puede comenzar la coincidencia. Un partido debe comenzar en o después de esta posición, lo que no supone un nuevo comienzo de la cuerda para patrones anclados.

occurrence selecciona la primera, segunda o posterior coincidencia no superpuesta encontrada entre start. group selecciona el texto que se debe devolver de esa coincidencia: 0 selecciona la coincidencia completa, y un valor positivo selecciona ese grupo de captura numerado. flags cambia el comportamiento de emparejamiento tal como se describe en las reglas y opciones de emparejamiento.

Si no se encuentra ninguna ocurrencia coincidente, o el grupo de captura seleccionado no participa en esa ocurrencia, la función devuelve nulo.

RETURN MSFT.REGEXP_SUBSTR(
  '12-345',
  '([0-9]+)-([0-9]+)',
  0,
  1,
  '',
  2
) AS matched_text

La primera aparición es la cadena completa, y el grupo 2 de captura es 345, por lo que el resultado es 345.

MSFT.REGEXP_REPLACE

Reemplaza el texto coincidente. Por defecto, reemplaza cada coincidencia e inserta el texto de reemplazo literalmente.

Argumentos Syntax
3 MSFT.REGEXP_REPLACE(source, pattern, [EXACT \| TEMPLATE] replacement)
4 MSFT.REGEXP_REPLACE(source, pattern, [EXACT \| TEMPLATE] replacement, start)
5 MSFT.REGEXP_REPLACE(source, pattern, [EXACT \| TEMPLATE] replacement, start, occurrence)
6 MSFT.REGEXP_REPLACE(source, pattern, [EXACT \| TEMPLATE] replacement, start, occurrence, flags)

source es la cadena a modificar e pattern identifica las coincidencias. replacement es el texto insertado para una partida seleccionada. EXACT lo inserta literalmente; TEMPLATE interpreta referencias de captura.

start es la posición de punto de código Unicode basada en cero en la que puede comenzar el reemplazo. Un combate debe comenzar en o después de esta posición. El texto anterior start se mantiene sin cambios, y la posición no se convierte en un nuevo comienzo de la cadena para patrones anclados. Establece occurrence que 0 reemplaza cada coincidencia de start, o a un valor positivo para reemplazar solo a esa coincidencia numerada no solapada. Las partidas anteriores posteriores start permanecen sin cambios cuando se selecciona una ocurrencia específica. flags cambia el comportamiento de emparejamiento tal como se describe en las reglas y opciones de emparejamiento.

RETURN MSFT.REGEXP_REPLACE('a1b2c3', '[0-9]', '#', 0, 2) AS replaced

Solo se reemplaza la coincidencia del segundo dígito, por lo que el resultado es a1b#c3.

Si no se encuentra coincidencia, la cadena fuente se devuelve sin cambios.

Para reutilizar texto coincidente en el reemplazo, especifica TEMPLATE. En este modo, \0\9 se refiere a los grupos completos de juego y captura, e \\ inserta una barra diagonal literal. Utiliza un literal de cadena en bruto, con el prefijo , @para pasar estas referencias sin escapar adicionalmente:

RETURN MSFT.REGEXP_REPLACE(
  'John Smith',
  @'([A-Za-z]+) ([A-Za-z]+)',
  TEMPLATE @'\2 \1'
) AS reordered_name

El resultado es Smith John.

Reglas y opciones de emparejamiento

Los patrones usan la sintaxis de expresiones regulares de RE2 y coinciden con cadenas Unicode. La fuente puede ser cualquier expresión de cadena. El patrón, las banderas y el reemplazo deben ser literales de cadena, y las opciones numéricas deben ser literales enteros sin signo.

Las coincidencias se encuentran de izquierda a derecha sin solapamiento. Tras una coincidencia de longitud cero, la emparejamiento avanza un punto de código Unicode.

Las posiciones iniciales y las devueltas son desplazamientos de puntos de código Unicode basados en cero. Los números de ocurrencia son basados en uno, excepto que ocurrencia 0 significa reemplazar a todas las ocurrencias en MSFT.REGEXP_REPLACE.

La siguiente tabla enumera los valores predeterminados para los argumentos opcionales omitidos:

Function Defaults
MSFT.REGEXP_LIKE Las banderas están vacías.
MSFT.REGEXP_COUNT Inicio es 0; las banderas están vacías.
MSFT.REGEXP_INSTR Start es 0; occurrence is 1; return option is 0; las banderas están vacías; group is 0.
MSFT.REGEXP_SUBSTR Inicio es 0; la ocurrencia es 1; las banderas están vacías; el grupo es 0.
MSFT.REGEXP_REPLACE Modo es EXACT; start is 0; occurrence is 0; las banderas están vacías.

Las banderas opcionales son:

Flag Comportamiento
i Empareja sin importar el caso.
m Haz ^ y $ combina el principio y el final de cada línea.
s Haz . que los personajes de nueva línea coincidan.

Combinar banderas en una sola cadena, como 'ims'. Una fuente nula devuelve nulo. Una bandera no soportada, una expresión regular inválida, una opción de retorno inválida o una ocurrencia inválida o número de grupo devuelve un error.

Funciones de grafo

  • nodes(path) : devuelve nodos de un valor de ruta de acceso.
  • edges(path) : devuelve bordes de un valor de ruta de acceso.
  • elements(path) : devuelve todos los nodos y bordes de una ruta de acceso como una sola lista, en orden de ruta de acceso.
  • labels(node_or_edge) : devuelve las etiquetas de un nodo o borde como una lista de cadenas.
  • path_length(path) : devuelve el número de bordes de una ruta de acceso.
  • element_id(node_or_edge) - devuelve el identificador de nodo o arista como una cadena opaca.

ELEMENT_ID acepta una referencia de nodo o arista y devuelve nulo para una entrada nula. Trata la cuerda devuelta como opaca.

Example:

MATCH p=(:Company)<-[:workAt]-(:Person)-[:knows]-{1,3}(:Person)-[:workAt]->(:Company)
RETURN nodes(p) AS chain_of_colleagues, path_length(p) AS hops

Enumerar funciones

  • size(list) : devuelve el tamaño de un valor de lista.
  • trim(list,n) - recorta una lista a como máximo n elementos.

Example:

MATCH (p:Person)-[:hasInterest]->(t:Tag)
LET personId = p.id, personName = p.firstName
RETURN personId, personName, collect_list(t.name) AS interests
GROUP BY personId, personName
FILTER size(interests) > 3

Funciones temporales

  • CURRENT_TIMESTAMP : devuelve la fecha y hora de zona actual.
  • ZONED_DATETIME(string) - devuelve la hora de fecha zonificada representada por una cadena ISO 8601.
  • DURATION(string) - devuelve la duración diurna representada por una cadena de duración ISO 8601.

Example:

RETURN CURRENT_TIMESTAMP AS now,
       DURATION('PT2H') AS twoHours

Utiliza el operador de resta para derivar una duración entre dos horas de fecha zonificadas:

RETURN ZONED_DATETIME('2026-09-17T12:00:00Z')
       - ZONED_DATETIME('2026-09-17T10:00:00Z') AS elapsed

Importante

Graph admite duraciones diurnas pero no duraciones anual-mes. DURATION_BETWEEN(start, end) actualmente no se soporta; resta los dos valores de fecha y hora zonificada en su lugar.

Funciones genéricas

  • coalesce(value1, value2, ...) : devuelve el primer valor distinto de NULL.
  • to_json_string(value) : convierte un valor en su representación de cadena JSON.

Example:

MATCH (p:Person)
RETURN coalesce(p.firstName, 'Unknown') AS display_name,
       to_json_string(p) AS person_json