As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Extensões do openCypher no Amazon Neptune
O Amazon Neptune oferece suporte à versão 9 da referência de especificação do openCypher. Consulte [Conformidade com especificações do openCypher no Amazon Neptune](feature-opencypher-compliance.md) no Amazon Neptune para obter detalhes. Além disso, o Amazon Neptune oferece suporte aos recursos listados aqui. A menos que versões específicas sejam mencionadas, os recursos estão disponíveis no banco de dados do Neptune e no Neptune Analytics.
## Query-time Acesso aos dados do S3
Disponível no Neptune Database 1.4.7.0 e superior.
O Neptune suporta `neptune.read()` a função de ler dados CSV ou Parquet do Amazon S3 diretamente nas consultas do OpenCypher. Ao contrário do carregador em massa, que importa dados antes da consulta, `neptune.read()` acessa os dados do Amazon S3 no momento da execução da consulta.
Para obter a documentação completa, consulte[netuno.read ()](access-graph-opencypher-21-extensions-s3-read.md).
## A função Neptune-specific `join ()`
Disponível no banco de dados do Neptune e no Neptune Analytics.
O Neptune implementa uma função `join()` que não está presente na especificação do openCypher. Ela cria uma string literal a partir de uma lista de literais de string e um delimitador de string. Usa dois argumentos:
+ O primeiro argumento é uma lista de literais de string.
+ O segundo argumento é a string delimitadora, que pode ser composta por zero, um ou mais de um caractere.
Exemplo:
```
join(["abc", "def", "ghi"], ", ") // Returns "abc, def, ghi"
```
## A função Neptune-specific `remove KeyFromMap ()`
Disponível no banco de dados do Neptune e no Neptune Analytics.
O Neptune implementa uma função `removeKeyFromMap()` que não está presente na especificação do openCypher. Ela remove uma chave especificada de um mapa e gera o novo mapa resultante.
A função utiliza dois argumentos:
+ O primeiro argumento é o mapa do qual remover a chave.
+ O segundo argumento é a chave a ser removida do mapa.
A função `removeKeyFromMap()` é particularmente útil em situações em que você deseja definir valores para um nó ou um relacionamento desenrolando uma lista de mapas. Por exemplo:
```
UNWIND [{`~id`: 'id1', name: 'john'}, {`~id`: 'id2', name: 'jim'}] as val
CREATE (n {`~id`: val.`~id`})
SET n = removeKeyFromMap(val, '~id')
```
## Valores de ID personalizados para propriedades de nó e relacionamento
Disponível no banco de dados do Neptune 1.2.0.2 e versões posteriores e no Neptune Analytics.
A partir da [versão 1.2.0.2 do mecanismo](engine-releases-1.2.0.2.md), o Neptune estendeu a especificação do openCypher para que agora você possa especificar os valores `id` dos nós e dos relacionamentos nas cláusulas `CREATE`, `MERGE` e `MATCH`. Isso permite que você atribua strings fáceis de usar em vez de UUIDs gerados pelo sistema para identificar nós e relacionamentos.
No Neptune Analytics, valores de identificação personalizados não estão disponíveis para bordas.
**Atenção**
Essa extensão da especificação do openCypher é incompatível com versões anteriores, porque agora `~id` é considerado um nome de propriedade reservado. Se você já estiver usando `~id` como propriedade em seus dados e consultas, precisará migrar a propriedade existente para uma nova chave de propriedade e remover a antiga. Consulte [O que fazer se você estiver usando atualmente `~id` como uma propriedade](#opencypher-compliance-custom-ids-migrating).
Veja um exemplo que mostra como criar nós e relacionamentos com IDS personalizados:
```
CREATE (n {`~id`: 'fromNode', name: 'john'})
-[:knows {`~id`: 'john-knows->jim', since: 2020}]
->(m {`~id`: 'toNode', name: 'jim'})
```
Se você tentar criar um ID personalizado que já esteja em uso, o Neptune gerará um erro `DuplicateDataException`.
Veja um exemplo do uso de um ID personalizado em uma cláusula `MATCH`:
```
MATCH (n {`~id`: 'id1'})
RETURN n
```
Veja um exemplo do uso de IDs personalizados em uma cláusula `MERGE`:
```
MATCH (n {name: 'john'}), (m {name: 'jim'})
MERGE (n)-[r {`~id`: 'john->jim'}]->(m)
RETURN r
```
### O que fazer se você estiver usando atualmente `~id` como uma propriedade
Com a [versão 1.2.0.2 do mecanismo](engine-releases-1.2.0.2.md), a chave `~id` nas cláusulas do openCypher agora é tratada como `id` e não como uma propriedade. Isso significa que, se você tiver uma propriedade denominada `~id`, o acesso a ela se tornará impossível.
Se você estiver usando uma propriedade `~id`, antes de realizar a atualização para a versão do mecanismo `1.2.0.2` ou superior, é necessário primeiro migrar a propriedade `~id` existente para uma nova chave de propriedade e depois remover a propriedade `~id`. Por exemplo, a consulta a seguir:
+ Cria uma propriedade denominada “newId” para todos os nós,
+ copia o valor da propriedade “\~id” para a propriedade “newId”
+ e remove a propriedade “\~id” dos dados
```
MATCH (n)
WHERE exists(n.`~id`)
SET n.newId = n.`~id`
REMOVE n.`~id`
```
O mesmo precisa ser feito para qualquer relacionamento nos dados que tenha uma propriedade `~id`.
Você também precisará alterar todas as consultas que estiver usando que façam referência a uma propriedade `~id`. Por exemplo, esta consulta:
```
MATCH (n)
WHERE n.`~id` = 'some-value'
RETURN n
```
... mudaria para isto:
```
MATCH (n)
WHERE n.newId = 'some-value'
RETURN n
```
## Suporte à subconsulta CALL no Neptune
Disponível no banco de dados do Neptune 1.4.1.0 e versões posteriores e no Neptune Analytics.
O Amazon Neptune oferece suporte a subconsultas `CALL`. Uma subconsulta `CALL` faz parte da consulta principal executada em um escopo isolado para cada entrada da subconsulta `CALL`.
Por exemplo, suponha que um grafo contenha dados sobre pessoas, amigos e cidades em que moram. Podemos recuperar as duas maiores cidades em que cada amigo de alguém morava usando uma subconsulta `CALL`:
```
MATCH (person:Person)-[:knows]->(friend)
CALL {
WITH friend
MATCH (friend)-[:lived_in]->(city)
RETURN city
ORDER BY city.population DESC
LIMIT 2
}
RETURN person, friend, city
```
Neste exemplo, a parte de consulta interna `CALL { ... }` é executada para cada `friend` que corresponda à cláusula MATCH anterior. Quando a consulta interna é executada, as cláusulas `ORDER` e `LIMIT` são os locais das cidades em que um amigo específico morava, então obtemos (no máximo) duas cidades por amigo.
Todas as cláusulas de consulta estão disponíveis dentro das subconsultas `CALL`. Isso também inclui subconsultas `CALL` aninhadas. Há algumas restrições para a primeira cláusula `WITH` e as variáveis emitidas, explicadas abaixo.
### Escopo das variáveis dentro da subconsulta CALL
As variáveis das cláusulas antes da subconsulta `CALL` que são usadas dentro dela devem ser importadas pela cláusula inicial `WITH`. Ao contrário das cláusulas `WITH` regulares, ela só pode conter uma lista de variáveis, mas não permite aliases e não pode ser usada com `DISTINCT`, `ORDER BY`, `WHERE`, `SKIP` ou `LIMIT`.
### Variáveis retornadas da subconsulta CALL
As variáveis emitidas pela subconsulta `CALL` são especificadas com a cláusula final `RETURN`. Observe que as variáveis emitidas não podem se sobrepor às variáveis antes da subconsulta `CALL`.
### Limitações
No momento, não há suporte para atualizações dentro de uma subconsulta `CALL`.
## Funções do openCypher no Neptune
Disponível no banco de dados do Neptune 1.4.1.0 e versões posteriores e no Neptune Analytics.
**texto IndexOf**
`textIndexOf(text :: STRING, lookup :: STRING, from = 0 :: INTEGER?, to = -1 :: INTEGER?) :: (INTEGER?)`
Retorna o índice da primeira ocorrência de `lookup` no intervalo de `text` começando no deslocamento `from` (inclusivo) até o deslocamento `to` (exclusivo). Se `to` for -1, o intervalo continua até o final de `text`. A indexação é baseada em zero e é expressa em valores escalares Unicode (pontos de código não substitutos).
```
RETURN textIndexOf('Amazon Neptune', 'e')
{
"results": [{
"textIndexOf('Amazon Neptune', 'e')": 8
}]
}
```
**coll ToSet**
`collToSet(values :: LIST OF ANY?) :: (LIST? OF ANY?)`
Retorna uma nova lista contendo somente os elementos exclusivos da lista original. A ordem da lista original é **mantida** (por exemplo, `[1, 6, 5, 1, 5]` retorna `[1, 6, 5]`).
```
RETURN collToSet([1, 6, 5, 1, 1, 5])
{
"results": [{
"collToSet([1, 6, 5, 1, 1, 5])": [1, 6, 5]
}]
}
```
**collSubtract**
`collSubtract(first :: LIST OF ANY?, second :: LIST OF ANY?) :: (LIST? OF ANY?)`
Retorna uma nova lista contendo todos os elementos únicos de `first` excluindo os elementos de `second`.
```
RETURN collSubtract([2, 5, 1, 0], [1, 5])
{
"results": [{
"collSubtract([2, 5, 1, 0], [1, 5])": [0, 2]
}]
}
```
**collIntersection**
`collIntersection(first :: LIST? OF ANY?, second :: LIST? OF ANY?) :: (LIST? OF ANY?)`
Retorna uma nova lista contendo todos os elementos únicos da interseção de `first` e `second`.
```
RETURN collIntersection([2, 5, 1, 0], [1, 5])
{
"results": [{
"collIntersection([2, 5, 1, 0], [1, 5])": [1, 5]
}]
}
```
## Funções de classificação
As seções a seguir definem funções para classificar coleções. Essas funções usam (em alguns casos opcionais) argumentos de `config` mapa ou uma lista de vários desses mapas, que definem a chave de classificação e and/or a direção de classificação:
```
{ key: STRING, order: STRING }
```
Aqui, `key` pode ser um mapa ou uma propriedade de nó cujo valor deve ser usado para classificação. `order` pode ser “`asc`” ou “`desc`” (sem distinção de maiúsculas ou minúsculas) para especificar uma classificação ascendente ou descendente, respectivamente. Por padrão, a classificação será executada em ordem crescente.
**collSort**
`collSort(coll :: LIST OF ANY, config :: MAP?) :: (LIST? OF ANY?)`
Retorna uma nova lista ordenada contendo os elementos da lista de entrada `coll`.
```
RETURN collSort([5, 3, 1], {order: 'asc'})
{
"results": [{
"collSort([5, 3, 1])": [1, 3, 5]
}]
}
```
**coll SortMaps**
`collSortMaps(coll :: LIST OF MAP, config :: MAP) :: (LIST? OF ANY?)`
Retorna uma lista de mapas classificados pelo valor da propriedade especificada `key`.
```
RETURN collSortMaps([{name: 'Alice', age: 25}, {name: 'Bob', age: 35}, {name: 'Charlie', age: 18}], {key: 'age', order: 'desc'})
{
"results": [{
"x": [{
"age": 35,
"name": "Bob"
}, {
"age": 25,
"name": "Alice"
}, {
"age": 18,
"name": "Charlie"
}]
}]
}
```
**coll SortMulti**
```
collSortMulti(coll :: LIST OF MAP?,
configs = [] :: LIST OF MAP,
limit = -1 :: INTEGER?,
skip = 0 :: INTEGER?) :: (LIST? OF ANY?)
```
Retorna uma lista de mapas classificados pelo valor das propriedades especificas `key`, aplicando opcionalmente limit e skip.
```
RETURN collSortMulti([{name: 'Alice', age: 25}, {name: 'Bob', age: 35}, {name: 'Charlie', age: 18}], [{key: 'age', order: 'desc'}, {key:'name'}]) as x
{
"results": [{
"x": [{
"age": 35,
"name": "Bob"
}, {
"age": 25,
"name": "Alice"
}, {
"age": 18,
"name": "Charlie"
}]
}]
}
```
**coll SortNodes**
`collSortNodes(coll :: LIST OF NODE, config :: MAP) :: (LIST? OF NODE?)`
Retorna uma versão ordenada da lista de entrada `coll`, classificando os elementos do nó pelos valores de suas respectivas propriedades `key`.
```
create (n:person {name: 'Alice', age: 23}), (m:person {name: 'Eve', age: 21}), (o:person {name:'Bob', age:25})
{"results":[]}
match (n:person) with collect(n) as people return collSortNodes(people, {key: 'name', order: 'desc'})
{
"results": [{
"collSortNodes(people, 'name')": [{
"~id": "e599240a-8c23-4337-8aa8-f603c8fb5488",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 21,
"name": "Eve"
}
}, {
"~id": "8a6ef785-59e3-4a0b-a0ff-389655a9c4e6",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 25,
"name": "Bob"
}
}, {
"~id": "466bc826-f47f-452c-8a27-6b7bdf7ae9b4",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 23,
"name": "Alice"
}
}]
}]
}
match (n:person) with collect(n) as people return collSortNodes(people, {key: 'age'})
{
"results": [{
"collSortNodes(people, '^age')": [{
"~id": "e599240a-8c23-4337-8aa8-f603c8fb5488",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 21,
"name": "Eve"
}
}, {
"~id": "466bc826-f47f-452c-8a27-6b7bdf7ae9b4",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 23,
"name": "Alice"
}
}, {
"~id": "8a6ef785-59e3-4a0b-a0ff-389655a9c4e6",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 25,
"name": "Bob"
}
}]
}]
}
```
## Funções temporais
As funções temporais estão disponíveis a partir da versão [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml) e superior do Neptune.
### dia
`day(temporal :: (datetime | date)) :: (LONG)`
Retorna o `day` do mês a partir de um `datetime` ou um valor `date`. Para `datetime`: os valores são normalizados para UTC com base na entrada antes de extrair o dia. Para `date`: o dia é extraído com base no fuso horário.
A entrada `datetime` está disponível no banco de dados do Neptune e no Neptune Analytics:
```
RETURN day(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"day(datetime('2021-06-03T01:48:14Z'))": 3
}]
}
```
Aqui, `datetime` é normalizado para UTC, então \+08:00 volta para 2 de junho.
```
RETURN day(datetime('2021-06-03T00:00:00+08:00'))
{
"results": [{
"day(datetime('2021-06-03T00:00:00+08:00'))": 2
}]
}
```
A entrada `date` está disponível somente no Neptune Analytics:
```
RETURN day(date('2021-06-03Z'))
{
"results": [{
"day(date('2021-06-03Z'))": 3
}]
}
```
A `date` preserva o fuso horário, mantendo 3 de junho.
```
RETURN day(date('2021-06-03+08:00'))
{
"results": [{
"day(date('2021-06-03+08:00'))": 3
}]
}
```
### mês
`month(temporal :: (datetime | date)) :: (LONG)`
Retorna o mês a partir de um `datetime` ou um valor de `date` (1-12). Para `datetime`: os valores são normalizados para UTC com base na entrada antes de extrair o mês. Para `date`: o mês é extraído com base no fuso horário.
A entrada `datetime` está disponível no banco de dados do Neptune e no Neptune Analytics:
```
RETURN month(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"month(datetime('2021-06-03T01:48:14Z'))": 6
}]
}
```
Aqui, `datetime` é normalizado para UTC, então \+08:00 volta para 31 de maio.
```
RETURN month(datetime('2021-06-01T00:00:00+08:00'))
{
"results": [{
"month(datetime('2021-06-01T00:00:00+08:00'))": 5
}]
}
```
A entrada `date` está disponível somente no Neptune Analytics:
```
RETURN month(date('2021-06-03Z'))
{
"results": [{
"month(date('2021-06-03Z'))": 6
}]
}
```
A `date` preserva o fuso horário, mantendo 1º de junho.
```
RETURN month(date('2021-06-01+08:00'))
{
"results": [{
"month(date('2021-06-01+08:00'))": 6
}]
}
```
### ano
`year(temporal :: (datetime | date)) :: (LONG)`
Retorna o ano a partir de um `datetime` ou um valor `date`. Para `datetime`: os valores são normalizados para UTC com base na entrada antes de extrair o ano. Para `date`: o ano é extraído com base no fuso horário.
A entrada `datetime` está disponível no banco de dados do Neptune e no Neptune Analytics:
```
RETURN year(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"year(datetime('2021-06-03T01:48:14Z'))": 2021
}]
}
```
Aqui, o `datetime` é normalizado para UTC, então \+08:00 volta para 31 de dezembro de 2020.
```
RETURN year(datetime('2021-01-01T00:00:00+08:00'))
{
"results": [{
"year(datetime('2021-01-01T00:00:00+08:00'))": 2020
}]
}
```
A entrada `date` está disponível somente no Neptune Analytics:
```
RETURN year(date('2021-06-03Z'))
{
"results": [{
"year(date('2021-06-03Z'))": 2021
}]
}
```
A `date` preserva o fuso horário, mantendo junho de 2021.
```
RETURN year(date('2021-01-01+08:00'))
{
"results": [{
"year(date('2021-01-01+08:00'))": 2021
}]
}
```
### Funções do openCypher no Neptune
Disponível no banco de dados do Neptune 1.4.6.0 e versões posteriores e no Neptune Analytics.
#### reduce()
O reduce processa sequencialmente cada elemento da lista combinando-o com um total em execução, ou “acumulador”. Começando com um valor inicial, ele atualiza o acumulador após cada operação e usa esse valor atualizado na próxima iteração.
`for i in (0, ..., n) acc = acc X list[I], where X denotes any binary operator`
Depois que todos os elementos forem processados, ele retornará o resultado final acumulado.
Uma estrutura típica de reduce() seria `reduce(accumulator = initial , variable IN list | expression)`
**Especificações de tipo:**
`- initial: starting value for the accumulator :: (Long | FLOAT | STRING | LIST? OF (STRING, LONG, FLOAT)) - list: the input list :: LIST OF T where T matches initial type - variable :: represents each element in the input list - expression :: Only supports '+' and '*' operator - return :: Same type as initial `
**Restrições:**
Atualmente, a expressão `reduce()` só oferece suporte a:
+ Multiplicação numérica
+ Adição numérica
+ Concatenação de strings
+ Concatenação de listas
Eles são representados pelo operador `+` ou `*`. A expressão deve ser uma expressão binária conforme especificado abaixo: `expression pattern: accumulator + any variable or accumulator * any variable`
**Tratamento de transbordamento:**
O Neptune detecta o transbordamento numérico durante a avaliação de `reduce()` e responde de forma diferente com base no tipo de dados:
```
LONG (signed 64‑bit)
--------------------
• Valid range: –9 223 372 036 854 775 808 … 9 223 372 036 854 775 807
• If any intermediate or final value falls outside this range,
Neptune aborts the query with long overflow error message.
FLOAT (IEEE‑754 double)
-----------------------
• Largest finite value ≈ 1.79 × 10^308
• Larger results overflow to INF
Once `INF` is produced, it propagates through the remainder
of the reduction.
```
**Exemplos:**
Veja os exemplos a seguir da função reduce().
```
1. Long Addition:
RETURN reduce(sum = 0, n IN [1, 2, 3] | sum + n)
{
"results": [{
"reduce(sum = 0, n IN [1, 2, 3] | sum + n)": 6
}]
}
2. String Concatenation:
RETURN reduce(str = "", x IN ["A", "B", "C"] | str + x)
{
"results": [{
"reduce(str = "", x IN ["A", "B", "C"] | str + x)": "ABC"
}]
}
3. List Combination:
RETURN reduce(lst = [], x IN [1, 2, 3] | lst + x)
{
"results": [{
"reduce(lst = [], x IN [1, 2, 3] | lst + x)": [1, 2, 3]
}]
}
4. Float Addition:
RETURN reduce(total = 0.0, x IN [1.5, 2.5, 3.5] | total + x)
{
"results": [{
"reduce(total = 0.0, x IN [1.5, 2.5, 3.5] | total + x)": 7.5
}]
}
5. Long Multiplication:
RETURN reduce(product = 1, n IN [1, 2, 3] | product * n)
{
"results": [{
"reduce(product = 0, n IN [1, 2, 3] | product * n)": 6
}]
}
6. Float Multiplication:
RETURN reduce(product = 1.0, n IN [1.5, 2.5, 3.5] | product * n)
{
"results": [{
"reduce(product = 1.0, n IN [1.5, 2.5, 3.5] | product * n)": 13.125
}]
}
7. Long Overflow (Exception):
RETURN reduce(s = 9223372036854775807, x IN [2, 3] | s * x) AS result
{
"results": [{
"reduce(s = 9223372036854775807, x IN [2, 3] | s * x) AS result": long overflow
}]
}
8. Float Overflow:
RETURN reduce(s = 9.0e307, x IN [8.0e307, 1.0e307] | s + x) AS result
{
"results": [{
"reduce(s = 9.0e307, x IN [8.0e307, 1.0e307] | s + x) AS result": INF
}]
}
```