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á.

# Acessar o grafo do Neptune com o SPARQL
<a name="access-graph-sparql"></a>

O SPARQL é uma linguagem de consulta para o Resource Description Framework (RDF), que é um formato de dados de grafos projetado para a web. O Amazon Neptune é compatível com o SPARQL 1.1. Isso significa que você pode se conectar a uma instância de banco de dados do Neptune e consultar o grafo usando a linguagem de consulta descrita na especificação [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/).

 Uma consulta no SPARQL consiste em uma cláusula `SELECT` para especificar as variáveis a serem retornadas e uma cláusula `WHERE` para especificar quais dados corresponder no gráfico. Se não estiver familiarizado com as consultas do SPARQL, consulte [Writing Simple Queries](https://www.w3.org/TR/sparql11-query/#WritingSimpleQueries) no [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/).

**Importante**  
Para carregar dados, `SPARQL UPDATE INSERT` pode funcionar bem para um pequeno conjunto de dados, mas se for necessário carregar uma quantidade significativa de dados de um arquivo, consulte [Usar o carregador em massa do Amazon Neptune para ingerir dados](bulk-load.md).

Para obter mais informações sobre as especificidades da implementação do SPARQL do Neptune, consulte [Conformidade com padrões do SPARQL](feature-sparql-compliance.md).

Antes de começar, você deve ter o seguinte:
+ Uma instância de banco de dados do Neptune. Para obter informações sobre como criar uma instância de banco de dados do Neptune, consulte [Criar um cluster do Amazon Neptune](get-started-create-cluster.md).
+ A instância do Amazon EC2 na mesma nuvem privada virtual (VPC) que a instância de banco de dados do Neptune.

**Topics**
+ [Usando o console RDF4 J para se conectar a uma instância de banco de dados Neptune](access-graph-sparql-rdf4j-console.md)
+ [Usando o RDF4 J Workbench para se conectar a uma instância de banco de dados Neptune](access-graph-sparql-rdf4j-workbench.md)
+ [Usar o Java para conectar-se a uma instância de banco de dados do Neptune](access-graph-sparql-java.md)
+ [API HTTP do SPARQL](sparql-api-reference.md)
+ [Dicas de consulta do SPARQL](sparql-query-hints.md)
+ [Comportamento do SPARQL DESCRIBE em relação ao grafo padrão](sparql-default-describe.md)
+ [API de status de consulta do SPARQL](sparql-api-status.md)
+ [Cancelamento de consulta do SPARQL](sparql-api-status-cancel.md)
+ [Usar o protocolo HTTP do SPARQL 1.1 Graph Store (GSP) no Amazon Neptune](sparql-graph-store-protocol.md)
+ [Analisar a execução de consulta do Neptune usando o `explain` do SPARQL](sparql-explain.md)
+ [Consultas federadas do SPARQL no Neptune usando a extensão `SERVICE`](sparql-service.md)

# Usando o console RDF4 J para se conectar a uma instância de banco de dados Neptune
<a name="access-graph-sparql-rdf4j-console"></a>



O RDF4 J Console permite que você experimente gráficos e consultas do Resource Description Framework (RDF) em um ambiente REPL (loop)read-eval-print . 

Você pode adicionar um banco de dados gráfico remoto como repositório e consultá-lo no RDF4 J Console. Esta seção mostra a configuração do RDF4 J Console para se conectar remotamente a uma instância de banco de dados Neptune.

**Para se conectar ao Neptune usando o J Console RDF4**

1. Faça o download do SDK do RDF4 J na [página de download](http://rdf4j.org/download/) no site do RDF4 J.

1. Descompacte o arquivo zip RDF4 J SDK.

1. Em um terminal, navegue até o diretório RDF4 J SDK e digite o seguinte comando para executar o RDF4 J Console:

   ```
   bin/console.sh
   ```

   Você deve ver uma saída semelhante a:

   ```
   14:11:51.126 [main] DEBUG o.e.r.c.platform.PlatformFactory - os.name = linux
   14:11:51.130 [main] DEBUG o.e.r.c.platform.PlatformFactory - Detected Posix platform
   Connected to default data directory
   RDF4J Console 3.6.1
   
   3.6.1
   Type 'help' for help.
   >
   ```

   Agora você está no prompt do `>`. Esse é o prompt geral do RDF4 J Console. Você usa esse prompt para configurar repositórios e outras operações. Um repositório tem seu próprio prompt para execução de consultas.

1. No prompt `>`, digite o seguinte para criar um repositório do SPARQL para a instância de banco de dados do Neptune:

    

   ```
   create sparql
   ```

1. O RDF4 J Console solicita valores para as variáveis necessárias para se conectar ao endpoint SPARQL.

   ```
   Please specify values for the following variables:
   ```

   Especifique os seguintes valores:    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/access-graph-sparql-rdf4j-console.html)

   Para obter informações sobre como localizar o endereço da instância de banco de dados do Neptune, consulte a seção [Conectar-se a endpoints do Amazon Neptune](feature-overview-endpoints.md).

   Se a operação for bem-sucedida, você verá a seguinte mensagem:

    

   ```
   Repository created
   ```

1. No prompt `>`, insira o seguinte para conectar-se à instância de banco de dados do Neptune:

   ```
   open neptune
   ```

   Se a operação for bem-sucedida, você verá a seguinte mensagem:

    

   ```
   Opened repository 'neptune'
   ```

   Agora você está no prompt do `neptune>`. Nesse prompt, é possível executar consultas no grafo do Neptune.

    
**nota**  
Agora que você adicionou o repositório, na próxima vez que executar o `bin/console.sh`, poderá executar o comando `open neptune` imediatamente para conectar-se à instância de banco de dados do Neptune.

1. No `neptune>` prompt, digite o seguinte para executar uma consulta SPARQL que retorna até 10 dos triplos (subject-predicate-object) no gráfico usando a `?s ?p ?o` consulta com um limite de 10. Para consultar outros elementos, substitua o texto depois do comando `sparql` com outra consulta do SPARQL.

   ```
   sparql select ?s ?p ?o where {?s ?p ?o} limit 10
   ```

# Usando o RDF4 J Workbench para se conectar a uma instância de banco de dados Neptune
<a name="access-graph-sparql-rdf4j-workbench"></a>

Esta seção mostra como se conectar a uma instância de banco de dados Amazon Neptune RDF4 usando o J RDF4 Workbench e o J Server. RDF4O J Server é necessário porque ele atua como um proxy entre o endpoint HTTP REST Neptune SPARQL e o J Workbench. RDF4 

RDF4O J Workbench fornece uma interface fácil para experimentar um gráfico, incluindo o carregamento de arquivos locais. Para obter informações, consulte a [seção Adicionar](https://rdf4j.org/documentation/tools/server-workbench/#add) na documentação RDF4 J.

**Pré-requisitos**  
Antes de começar, faça o seguinte:
+ Instale o Java 1.8 ou posterior.
+ Instale o RDF4 J Server e o RDF4 J Workbench. Para obter informações, consulte [Instalando o RDF4 J Server e o RDF4 J Workbench](https://rdf4j.org/documentation/tools/server-workbench/#installing-rdf4j-server-and-rdf4j-workbench).

**Para usar o RDF4 J Workbench para se conectar ao Neptune**

1. Em um navegador da web, navegue até a URL em que o aplicativo web RDF4 J Workbench está implantado. Por exemplo, se você estiver usando o Apache Tomcat, a URL será: [https: //:8080/rdf4j-workbench/](http://localhost:8080/rdf4j-workbench/). *ec2\$1hostname*

1. Se você for solicitado a se **conectar ao RDF4 J Server**, verifique se o **RDF4J Server** está instalado, em execução e se a URL do servidor está correta. Em seguida, prossiga para a próxima etapa.

1. No painel à esquerda, escolha **New repository (Novo repositório)**.

   Em **New repository (Novo repositório)**:
   + Na lista suspensa **Type (Tipo)**, escolha **SPARQL endpoint proxy (Proxy do endpoint do SPARQL)**.
   + Em **ID**, digite **neptune**.
   + Em **Título**, digite **Instância de banco de dados do Neptune**.

   Escolha **Próximo**.

1. Em **New repository (Novo repositório)**:
   + Em **SPARQL query endpoint URL (URL do endpoint de consulta do SPARQL)**, digite `https://your-neptune-endpoint:port/sparql`.
   + Em **SPARQL update endpoint URL (URL do endpoint de atualização do SPARQL)**, digite `https://your-neptune-endpoint:port/sparql`.

   Para obter informações sobre como localizar o endereço da instância de banco de dados do Neptune, consulte a seção [Conectar-se a endpoints do Amazon Neptune](feature-overview-endpoints.md). 

   Escolha **Criar**.

1. O repositório do **neptune** agora é exibido na lista de repositórios. Pode levar alguns minutos para que você possa usar o novo repositório.

1. Na coluna **Id** da tabela, escolha o link **neptune**.

1. No painel à esquerda, escolha **Query (Consultar)**. 

    
**nota**  
Se os itens do menu em **Explorar** estiverem desativados, talvez seja necessário se reconectar ao RDF4 J Server e escolher o repositório **neptune** novamente.  
Você pode fazer isso usando os links de **[change] (alterar)** no canto superior direito.

1. No campo de consulta, digite a seguinte consulta do SPARQL e, em seguida, selecione **Execute (Executar)**.

    

   ```
   select ?s ?p ?o where {?s ?p ?o} limit 10
   ```

    

O exemplo anterior retorna até 10 dos triples (subject-predicate-object) no gráfico usando a `?s ?p ?o` consulta com um limite de 10. 

# Usar o Java para conectar-se a uma instância de banco de dados do Neptune
<a name="access-graph-sparql-java"></a>

Esta seção descreve a execução de um exemplo completo de Java que se conecta a uma instância de banco de dados do Amazon Neptune e executa uma consulta do SPARQL.

Siga estas instruções em uma instância do Amazon EC2 na mesma nuvem privada virtual (VPC) que a instância de banco de dados do Neptune.

**Como conectar-se ao Neptune usando o Java**

1. Instale o Apache Maven na instância do EC2. Se estiver usando o Amazon Linux 2023 (preferencial), use:

   ```
   sudo dnf update -y
   sudo dnf install maven -y
   ```

   Se estiver usando o Amazon Linux 2, baixe o binário mais recente em [https://maven.apache.org/download.cgi: ](https://maven.apache.org/download.cgi:)

   ```
   sudo yum remove maven -y
   wget https://dlcdn.apache.org/maven/maven-3/ <version>/binaries/apache-maven-<version>-bin.tar.gz
   sudo tar -xzf apache-maven-<version>-bin.tar.gz -C /opt/
   sudo ln -sf /opt/apache-maven-<version> /opt/maven
   echo 'export MAVEN_HOME=/opt/maven' >> ~/.bashrc
   echo 'export PATH=$MAVEN_HOME/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc
   ```

1. Este exemplo foi testado apenas com o Java 8. Insira o seguinte para instalar o Java 8 na instância do EC2:

   ```
   sudo yum install java-1.8.0-devel
   ```

1. Insira o seguinte para definir o Java 8 como o tempo de execução padrão na instância do EC2:

   ```
   sudo /usr/sbin/alternatives --config java
   ```

   Quando solicitado, insira o número do Java 8.

1. Insira o seguinte para definir o Java 8 como o compilador padrão na instância do EC2: 

   ```
   sudo /usr/sbin/alternatives --config javac
   ```

   Quando solicitado, insira o número do Java 8.

1. Em um novo diretório, crie um arquivo `pom.xml` e abra-o em um editor de texto.

1. Copie o seguinte no arquivo `pom.xml` e salve-o (geralmente é possível ajustar os números da versão para a versão estável mais recente):

   ```
   <project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.amazonaws</groupId>
     <artifactId>RDFExample</artifactId>
     <packaging>jar</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>RDFExample</name>
     <url>https://maven.apache.org</url>
     <dependencies>
       <dependency>
         <groupId>org.eclipse.rdf4j</groupId>
         <artifactId>rdf4j-runtime</artifactId>
         <version>3.6</version>
       </dependency>
     </dependencies>
     <build>
       <plugins>
         <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>exec-maven-plugin</artifactId>
             <version>1.2.1</version>
             <configuration>
               <mainClass>com.amazonaws.App</mainClass>
             </configuration>
         </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
           <configuration>
             <source>1.8</source>
             <target>1.8</target>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>
   ```
**nota**  
Se estiver modificando um projeto existente do Maven, a dependência necessária será destacada no código anterior.

1. Para criar subdiretórios para o código-fonte de exemplo (`src/main/java/com/amazonaws/`), digite o seguinte na linha de comando:

   ```
   mkdir -p src/main/java/com/amazonaws/
   ```

1. No diretório `src/main/java/com/amazonaws/`, crie um arquivo denominado `App.java` e abra-o em um editor de texto.

1. Copie o seguinte no arquivo `App.java`. *your-neptune-endpoint*Substitua pelo endereço da sua instância de banco de dados Neptune.
**nota**  
Para obter informações sobre como localizar o nome do host da instância de banco de dados do Neptune, consulte a seção [Conectar-se a endpoints do Amazon Neptune](feature-overview-endpoints.md). 

   ```
   package com.amazonaws;
   
   import org.eclipse.rdf4j.repository.Repository;
   import org.eclipse.rdf4j.repository.http.HTTPRepository;
   import org.eclipse.rdf4j.repository.sparql.SPARQLRepository;
   
   import java.util.List;
   import org.eclipse.rdf4j.RDF4JException;
   import org.eclipse.rdf4j.repository.RepositoryConnection;
   import org.eclipse.rdf4j.query.TupleQuery;
   import org.eclipse.rdf4j.query.TupleQueryResult;
   import org.eclipse.rdf4j.query.BindingSet;
   import org.eclipse.rdf4j.query.QueryLanguage;
   import org.eclipse.rdf4j.model.Value;
   
   public class App
   {
       public static void main( String[] args )
       {
           String sparqlEndpoint = "https://your-neptune-endpoint:port/sparql";
           Repository repo = new SPARQLRepository(sparqlEndpoint);
           repo.initialize();
   
           try (RepositoryConnection conn = repo.getConnection()) {
              String queryString = "SELECT ?s ?p ?o WHERE { ?s ?p ?o } limit 10";
   
              TupleQuery tupleQuery = conn.prepareTupleQuery(QueryLanguage.SPARQL, queryString);
   
              try (TupleQueryResult result = tupleQuery.evaluate()) {
                 while (result.hasNext()) {  // iterate over the result
                      BindingSet bindingSet = result.next();
   
                      Value s = bindingSet.getValue("s");
                      Value p = bindingSet.getValue("p");
                      Value o = bindingSet.getValue("o");
   
                      System.out.print(s);
                      System.out.print("\t");
                      System.out.print(p);
                      System.out.print("\t");
                      System.out.println(o);
                 }
              }
           }
       }
   }
   ```

1. Use o comando do Maven a seguir para compilar e executar o exemplo:

   ```
   mvn compile exec:java
   ```

O exemplo anterior retorna até 10 dos triples (subject-predicate-object) no gráfico usando a `?s ?p ?o` consulta com um limite de 10. Para consultar outro elemento, substitua a consulta por outra consulta do SPARQL.

A iteração dos resultados no exemplo imprime o valor de cada variável retornada. O objeto `Value` é convertido em um `String` e, em seguida, é impresso. Se alterar a parte `SELECT` da consulta, você deverá modificar o código.

# API HTTP do SPARQL
<a name="sparql-api-reference"></a>

As solicitações HTTP do SPARQL são aceitas no seguinte endpoint: `https://your-neptune-endpoint:port/sparql`

Para obter mais informações sobre como se conectar ao Amazon Neptune com o SPARQL, consulte [Acessar o grafo do Neptune com o SPARQL](access-graph-sparql.md).

Para obter mais informações sobre o protocolo e a linguagem de consulta SPARQL, consulte o [Protocolo SPARQL 1.1](https://www.w3.org/TR/sparql11-protocol/#protocol) e a especificação [SPARQL 1.1 Query Language](https://www.w3.org/TR/sparql11-query/).

Os tópicos a seguir fornecem informações sobre formatos de serialização do RDF SPARQL e como usar a API HTTP do SPARQL com Neptune.

**Contents**
+ [Usar o endpoint REST HTTP para conectar-se a uma instância de banco de dados do Neptune](access-graph-sparql-http-rest.md)
+ [Cabeçalhos finais HTTP opcionais para respostas SPARQL de várias partes](access-graph-sparql-http-trailing-headers.md)
+ [Tipos de mídia do RDF usados pelo SPARQL no Neptune](sparql-media-type-support.md)
  + [Formatos de serialização do RDF usados pelo SPARQL no Neptune](sparql-media-type-support.md#sparql-serialization-formats)
  + [Formatos de serialização de resultado do SPARQL usados pelo SPARQL no Neptune](sparql-media-type-support.md#sparql-serialization-formats-neptune-output)
  + [Tipos de mídia que o Neptune pode usar para importar dados do RDF](sparql-media-type-support.md#sparql-serialization-formats-input)
  + [Tipos de mídia que o Neptune pode usar para exportar resultados de consulta](sparql-media-type-support.md#sparql-serialization-formats-output)
+ [Usar SPARQL UPDATE LOAD para importar dados para o Neptune](sparql-api-reference-update-load.md)
+ [Usar o SPARQL UPDATE UNLOAD para excluir dados do Neptune](sparql-api-reference-unload.md)

# Usar o endpoint REST HTTP para conectar-se a uma instância de banco de dados do Neptune
<a name="access-graph-sparql-http-rest"></a>

**nota**  
Atualmente, o Neptune não oferece suporte a HTTP/2 para solicitações da API REST. Os clientes devem usar HTTP/1.1 ao se conectar aos endpoints.

As instruções a seguir explicam como conectar-se ao endpoint do SPARQL usando o comando **curl** e conectando-se por meio de HTTPS e usando a sintaxe HTTP. Siga estas instruções em uma instância do Amazon EC2 na mesma nuvem privada virtual (VPC) que a instância de banco de dados do Neptune.

O endpoint HTTP para consultas do SPARQL a uma instância de banco de dados do Neptune é `https://your-neptune-endpoint:port/sparql`.

**nota**  
Para obter informações sobre como localizar o nome do host da instância de banco de dados do Neptune, consulte a seção [Conectar-se a endpoints do Amazon Neptune](feature-overview-endpoints.md).

O Amazon Neptune fornece um endpoint HTTP para consultas do SPARQL. A interface REST é compatível com o SPARQL versão 1.1.

**CONSULTA usando HTTP POST**  
O exemplo a seguir usa o **curl** para enviar uma **`QUERY`** do SPARQL por meio do HTTP **POST**.

```
curl -X POST --data-binary 'query=select ?s ?p ?o where {?s ?p ?o} limit 10' https://your-neptune-endpoint:port/sparql
```

O exemplo anterior retorna até 10 dos triples (subject-predicate-object) no gráfico usando a `?s ?p ?o` consulta com um limite de 10. Para consultar outro elemento, substitua-a por outra consulta do SPARQL.

**nota**  
O tipo de mídia MIME padrão de uma resposta é `application/sparql-results+json` para consultas `SELECT` e `ASK`.  
O tipo MIME padrão de uma resposta é `application/n-quads` para `CONSTRUCT` e consultas `DESCRIBE`.  
Para obter uma lista dos tipos de mídia usados pelo Neptune para serialização, consulte [Formatos de serialização do RDF usados pelo SPARQL no Neptune](sparql-media-type-support.md#sparql-serialization-formats).

**UPDATE usando HTTP POST**  
O exemplo a seguir usa o **curl** para enviar uma **`UPDATE`** do SPARQL por meio do HTTP **POST**.

```
curl -X POST --data-binary 'update=INSERT DATA { <https://test.com/s> <https://test.com/p> <https://test.com/o> . }' https://your-neptune-endpoint:port/sparql
```

O exemplo anterior insere o seguinte triplo no gráfico padrão do SPARQL: `<https://test.com/s> <https://test.com/p> <https://test.com/o>`

# Cabeçalhos finais HTTP opcionais para respostas SPARQL de várias partes
<a name="access-graph-sparql-http-trailing-headers"></a>

A resposta HTTP às consultas e atualizações do SPARQL geralmente é retornada em mais de uma parte ou fragmento. Pode ser difícil diagnosticar uma falha ocorrida após uma consulta ou uma atualização começar a enviar esses fragmentos, especialmente porque o primeiro chega com um código de status HTTP de `200`.

A menos que você solicite explicitamente os cabeçalhos finais, o Neptune só relata essa falha anexando uma mensagem de erro ao corpo da mensagem, que geralmente está corrompida.

Para facilitar a detecção e o diagnóstico desse tipo de problema, é possível incluir um cabeçalho de trailers com codificação de transferência (TE) (`te: trailers`) na solicitação (consulte, por exemplo, [a página MDN sobre cabeçalhos de solicitação TE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE)). Isso fará com que o Neptune inclua dois novos campos de cabeçalho nos cabeçalhos finais dos blocos de resposta:
+ `X-Neptune-Status`: contém o código de resposta seguido por um nome curto. Por exemplo, em caso de êxito, o cabeçalho final seria: `X-Neptune-Status: 200 OK`. Em caso de falha, o código de resposta seria um [código de erro do mecanismo do Neptune](errors-engine-codes.md), como `X-Neptune-Status: 500 TimeLimitExceededException`.
+ `X-Neptune-Detail`: fica em branco para solicitações bem-sucedidas. No caso de erros, ele contém a mensagem de erro JSON. Como somente caracteres ASCII são permitidos nos valores do cabeçalho HTTP, a string JSON é codificada em URL. A mensagem de erro também ainda é anexada ao corpo da mensagem de resposta.

# Tipos de mídia do RDF usados pelo SPARQL no Neptune
<a name="sparql-media-type-support"></a>

Os dados Resource Description Framework (RDF) podem ser serializados de muitas maneiras diferentes. A maioria delas pode ser consumida ou gerada por SPARQL:

## Formatos de serialização do RDF usados pelo SPARQL no Neptune
<a name="sparql-serialization-formats"></a>
+ **RDF/XML**: serialização XML do RDF, definida em [RDF 1.1 XML Syntax](https://www.w3.org/TR/rdf-syntax-grammar/). Tipo de mídia: `application/rdf+xml`. Extensão de arquivo típica: `.rdf`.
+ **N-Triples**: formato de texto simples com base em linha para codificar um grafo do RDF, definido em [RDF 1.1 N-Triples](https://www.w3.org/TR/n-triples/). Tipo de mídia: `application/n-triples`, `text/turtle` ou `text/plain`. Extensão de arquivo típica: `.nt`.
+ **N-Quads**: formato de texto simples com base em linha para codificar um grafo do RDF, definido em [RDF 1.1 N-Quads](https://www.w3.org/TR/n-quads/). Ele é uma extensão do N-Triples. Tipo de mídia: `application/n-quads` ou `text/x-nquads` quando codificado com US-ASCII de 7 bits. Extensão de arquivo típica: `.nq`.
+ **Turtle**: sintaxe textual para RDF definida em [RDF 1.1 Turtle](https://www.w3.org/TR/turtle/) que permite a um grafo do RDF ser completamente escrito em um formato de texto compacto e natural, com abreviações para tipos de dados e padrões de uso comuns. Turtle oferece níveis de compatibilidade com o formato N-Triples, bem como a sintaxe do padrão triplo do SPARQL. Tipo de mídia: `text/turtle`Extensão de arquivo típica: `.ttl`.
+ **TriG**: sintaxe textual para RDF definida em [RDF 1.1 TriG](https://www.w3.org/TR/trig/) que permite a um grafo do RDF ser completamente escrito em um formato de texto compacto e natural, com abreviações para tipos de dados e padrões de uso comuns. TriG é uma extensão do formato Turtle. Tipo de mídia: `application/trig`. Extensão de arquivo típica: `.trig`.
+ **N3 (Notation3)**: linguagem de lógica e asserção definida em [Notation3 (N3)Notation3 (N3): A readable RDF syntax](https://www.w3.org/TeamSubmission/n3/). N3 estende o modelo de dados RDF adicionando fórmulas (literais que são gráficos em si), variáveis, implicação lógica e predicados funcionais, e fornece uma sintaxe textual alternativa para RDF/XML. Tipo de mídia: `text/n3`. Extensão de arquivo típica: `.n3`.
+ **JSON-LD**: formato de mensagens e serialização de dados definido em [JSON-LD 1.0.](https://www.w3.org/TR/json-ld/)Media type: `application/ld+json`. Extensão de arquivo típica: `.jsonld`.
+ **TriX**: serialização de RDF em XML, definida em [TriX: RDF Triples in XML](https://www.hpl.hp.com/techreports/2004/HPL-2004-56.html). Tipo de mídia: `application/trix`. Extensão de arquivo típica: `.trix`.
+ **Resultados SPARQL JSON**: serialização do RDF usando o [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json). Tipo de mídia: `application/sparql-results+json`. Extensão de arquivo típica: `.srj`.
+ **RDF4Formato binário J** — Um formato binário para codificar dados RDF, documentado no formato [RDF4J Binary RDF](https://rdf4j.org/documentation/reference/rdf4j-binary). Tipo de mídia: `application/x-binary-rdf`.

## Formatos de serialização de resultado do SPARQL usados pelo SPARQL no Neptune
<a name="sparql-serialization-formats-neptune-output"></a>
+ **Resultados XML do SPARQL**: formato XML para os formatos de resultados boolianos e de vinculação variável fornecidos pela linguagem de consulta SPARQL, definida em [SPARQL Query Results XML Format (Second Edition)](https://www.w3.org/TR/rdf-sparql-XMLres/). Tipo de mídia: `application/sparql-results+xml`. Extensão de arquivo típica: `.srx`.
+ **Resultados CSV e TSV do SPARQL**: a utilização de valores separados por vírgula ou por tabulação para expressar os resultados de consulta do SPARQL de consultas `SELECT`, definido em [SPARQL 1.1 Query Results CSV and TSV Formats](https://www.w3.org/TR/sparql11-results-csv-tsv/). Tipo de mídia: `text/csv` para valores separados por vírgula e `text/tab-separated-values` para valores separados por tabulação. Extensões de arquivo típicas: `.csv` para valores separados por vírgula e `.tsv` para valores separados por tabulação.
+ **Tabela de resultados binários**: formato binário para codificar a saída de consultas do SPARQL. Tipo de mídia: `application/x-binary-rdf-results-table`.
+ **Resultados SPARQL JSON**: serialização do RDF usando o [SPARQL 1.1 Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/). Tipo de mídia: `application/sparql-results+json`.

## Tipos de mídia que o Neptune pode usar para importar dados do RDF
<a name="sparql-serialization-formats-input"></a>

**Tipos de mídia compatíveis com o [carregador em massa do Neptune](bulk-load.md)**
+ [N-Triples](https://www.w3.org/TR/n-triples/)
+ [N-Quads](https://www.w3.org/TR/n-quads/)
+ [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/)
+ [Turtle](https://www.w3.org/TR/turtle/)

**Tipos de mídia que SPARQL UPDATE LOAD pode importar**
+ [N-Triples](https://www.w3.org/TR/n-triples/)
+ [N-Quads](https://www.w3.org/TR/n-quads/)
+ [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/)
+ [Turtle](https://www.w3.org/TR/turtle/)
+ [TriG](https://www.w3.org/TR/trig/)
+ [N3](https://www.w3.org/TeamSubmission/n3/)
+ [JSON-LD](https://www.w3.org/TR/json-ld/)

## Tipos de mídia que o Neptune pode usar para exportar resultados de consulta
<a name="sparql-serialization-formats-output"></a>

Para especificar o formato de saída para uma resposta de consulta SPARQL, envie um cabeçalho `"Accept: media-type"` com a solicitação de consulta. Por exemplo:

```
curl -H "Accept: application/nquads" ...
```

**Tipos de mídia do RDF que o SPARQL SELECT pode gerar do Neptune**
+ [Resultados JSON SPARQL](https://www.w3.org/TR/sparql11-results-json) (este é o padrão)
+ [Resultados XML SPARQL](https://www.w3.org/TR/rdf-sparql-XMLres/)
+ **Tabela de resultados binários** (tipo de mídia: `application/x-binary-rdf-results-table`)
+ [CSV (valores separados por vírgula)](https://www.w3.org/TR/sparql11-results-csv-tsv/)
+ [TSB (valores separados por tabulação)](https://www.w3.org/TR/sparql11-results-csv-tsv/)

**Tipos de mídia do RDF que o SPARQL ASK pode gerar do Neptune**
+ [Resultados JSON SPARQL](https://www.w3.org/TR/sparql11-results-json) (este é o padrão)
+ [Resultados XML SPARQL](https://www.w3.org/TR/rdf-sparql-XMLres/)
+ **Booleano** (tipo de mídia: `text/boolean`, o que significa "verdadeiro" ou "falso")

**Tipos de mídia do RDF que o SPARQL CONSTRUCT pode gerar do Neptune**
+ [N-Quads](https://www.w3.org/TR/n-quads/) (este é o padrão)
+ [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/)
+ [JSON-LD](https://www.w3.org/TR/json-ld/)
+ [N-Triples](https://www.w3.org/TR/n-triples/)
+ [Turtle](https://www.w3.org/TR/turtle/)
+ [N3](https://www.w3.org/TeamSubmission/n3/)
+ [TriX](https://www.hpl.hp.com/techreports/2004/HPL-2004-56.html)
+ [TriG](https://www.w3.org/TR/trig/)
+ [Resultados JSON SPARQL](https://www.w3.org/TR/sparql11-results-json)
+ [RDF4Formato RDF binário J](https://rdf4j.org/documentation/reference/rdf4j-binary)

**Tipos de mídia do RDF que o SPARQL DESCRIBE pode gerar do Neptune**
+ [N-Quads](https://www.w3.org/TR/n-quads/) (este é o padrão)
+ [RDF/XML](https://www.w3.org/TR/rdf-syntax-grammar/)
+ [JSON-LD](https://www.w3.org/TR/json-ld/)
+ [N-Triples](https://www.w3.org/TR/n-triples/)
+ [Turtle](https://www.w3.org/TR/turtle/)
+ [N3](https://www.w3.org/TeamSubmission/n3/)
+ [TriX](https://www.hpl.hp.com/techreports/2004/HPL-2004-56.html)
+ [TriG](https://www.w3.org/TR/trig/)
+ [Resultados JSON SPARQL](https://www.w3.org/TR/sparql11-results-json)
+ [RDF4Formato RDF binário J](https://rdf4j.org/documentation/reference/rdf4j-binary)

# Usar SPARQL UPDATE LOAD para importar dados para o Neptune
<a name="sparql-api-reference-update-load"></a>

A sintaxe do comando SPARQL UPDATE LOAD é especificada na [recomendação de atualização do SPARQL 1.1](https://www.w3.org/TR/sparql11-update/#load):

```
LOAD SILENT (URL of data to be loaded) INTO GRAPH (named graph into which to load the data)
```
+ **`SILENT`**: (*opcional*) faz com que a operação seja bem-sucedida mesmo que tenha ocorrido um erro durante o processamento.

  Isso pode ser útil quando uma única transação contém várias declarações, como `"LOAD ...; LOAD ...; UNLOAD ...; LOAD ...;"` e você deseja que a transação seja concluída mesmo que alguns dos dados remotos não possam ser processados.
+ *URL of data to be loaded*— (*Obrigatório*) Especifica um arquivo de dados remoto contendo dados a serem carregados em um gráfico.

  O arquivo remoto deve ter uma das seguintes extensões:
  + `.nt`para NTriples.
  + `.nq`para NQuads.
  + `.trig` para Trig.
  + `.rdf` para RDF/XML.
  + `.ttl` para Turtle.
  + `.n3` para N3.
  + `.jsonld` para JSON-LD.
+ **`INTO GRAPH`***(named graph into which to load the data)*— (*Opcional*) Especifica o gráfico no qual os dados devem ser carregados.

  O Neptune associa cada triplo a um grafo nomeado. É possível especificar o grafo nomeado padrão usando o URI do grafo nomeado de fallback, `http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`, da seguinte forma:

  ```
  INTO GRAPH <http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph>
  ```

**nota**  
Quando você precisar carregar muitos dados, recomendamos usar o carregador em massa do Neptune em vez de UPDATE LOAD. Para obter mais informações sobre o carregador em massa, consulte [Usar o carregador em massa do Amazon Neptune para ingerir dados](bulk-load.md).

É possível usar `SPARQL UPDATE LOAD` para carregar dados diretamente do Amazon S3 ou de arquivos obtidos de um servidor da web hospedado automaticamente. Os recursos a serem carregados devem residir na mesma região que o servidor do Neptune, e o endpoint para os recursos deve ter permissão na VPC. Para obter informações sobre como criar um endpoint do Amazon S3, consulte [Criar o endpoint da VPC do Amazon S3](bulk-load-data.md#bulk-load-prereqs-s3).

Tudo `SPARQL UPDATE LOAD` URIs deve começar com`https://`. Isso inclui o Amazon S3 URLs.

Ao contrário do carregador em massa do Neptune, uma chamada para `SPARQL UPDATE LOAD` é totalmente transacional.

**Carregar arquivos diretamente do Amazon S3 no Neptune usando SPARQL UPDATE LOAD**

Como o Neptune não permite que você transmita um perfil do IAM para o Amazon S3 ao usar SPARQL UPDATE LOAD, o bucket do Amazon S3 em questão deve ser público ou você deve usar um [URL do Amazon S3 pré-assinado](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) na consulta LOAD.

Para gerar uma URL pré-assinada para um arquivo Amazon S3, você pode usar AWS CLI um comando como este:

```
aws s3 presign --expires-in (number of seconds) s3://(bucket name)/(path to file of data to load)
```

Depois, é possível usar o URL pré-assinado resultante no comando `LOAD`:

```
curl https://(a Neptune endpoint URL):8182/sparql \
  --data-urlencode 'update=load (pre-signed URL of the remote Amazon S3 file of data to be loaded) \
                           into graph (named graph)'
```

Para obter mais informações, consulte [Autenticação de solicitações: usando parâmetros de consulta](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html). A [documentação do Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-presigned-urls.html) mostra como usar um script Python para gerar um URL pré-assinado.

Além disso, o tipo de conteúdo dos arquivos a serem carregados deve ser definido corretamente.

1. Defina o tipo de conteúdo de arquivos ao fazer upload deles no Amazon S3 usando o parâmetro `-metadata`, como:

   ```
   aws s3 cp test.nt s3://bucket-name/my-plain-text-input/test.nt --metadata Content-Type=text/plain
   aws s3 cp test.rdf s3://bucket-name/my-rdf-input/test.rdf --metadata Content-Type=application/rdf+xml
   ```

1. Confirme se as informações de tipo de mídia estão realmente presentes. Execute:

   ```
   curl -v bucket-name/folder-name
   ```

   A saída desse comando deve mostrar as informações de tipo de mídia que você define ao carregar os arquivos.

1. Depois, você pode usar o comando `SPARQL UPDATE LOAD` para importar esses arquivos para o Neptune:

   ```
   curl https://your-neptune-endpoint:port/sparql \
     -d "update=LOAD <https://s3.amazonaws.com/bucket-name/my-rdf-input/test.rdf>"
   ```

As etapas acima funcionam apenas para um bucket público do Amazon S3 ou para um bucket que você acessa usando um [URL do Amazon S3 pré-assinado](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) na consulta LOAD.

 Você também pode configurar um servidor de proxy web para carregar a partir de um bucket privado do Amazon S3, conforme mostrado abaixo:

**Usar um servidor da web para carregar arquivos no Neptune com SPARQL UPDATE LOAD**

1. Instale um servidor da web em uma máquina em execução na VPC que está hospedando Neptune e os arquivos a serem carregados. Por exemplo, usando o Amazon Linux, você pode instalar o Apache da seguinte forma:

   ```
   sudo yum install httpd mod_ssl
   sudo /usr/sbin/apachectl start
   ```

1. Defina os tipos MIME do conteúdo do arquivo RDF que você carregar. O SPARQL usa o cabeçalho `Content-type` enviado pelo servidor da Web para determinar o formato de entrada do conteúdo, portanto, é necessário definir tipos MIME relevantes para o servidor da Web.

   Por exemplo, suponha que você use as seguintes extensões de arquivo para identificar formatos de arquivo:
   + `.nt`para NTriples.
   + `.nq`para NQuads.
   + `.trig` para Trig.
   + `.rdf` para RDF/XML.
   + `.ttl` para Turtle.
   + `.n3` para N3.
   + `.jsonld` para JSON-LD.

   Se você estiver usando o Apache 2 como servidor da Web, edite o arquivo `/etc/mime.types` e adicione os seguintes tipos:

   ```
    text/plain nt
    application/n-quads nq
    application/trig trig
    application/rdf+xml rdf
    application/x-turtle ttl
    text/rdf+n3 n3
    application/ld+json jsonld
   ```

1. Confirme se o mapeamento do tipo MIME funciona. Quando você tiver o servidor da Web em execução e hospedando arquivos RDF nos formatos de sua escolha, poderá testar a configuração enviando uma solicitação para o servidor da Web do seu host local.

   Por exemplo, você pode enviar uma solicitação como esta:

   ```
   curl -v http://localhost:80/test.rdf
   ```

   Em seguida, na saída detalhada de `curl`, você deve ver uma linha como:

   ```
   Content-Type: application/rdf+xml
   ```

   Isso mostra que o mapeamento de tipo de conteúdo foi definido com êxito.

1. Agora você está com tudo pronto para carregar dados usando o comando SPARQL UDPATE:

   ```
   curl https://your-neptune-endpoint:port/sparql \
       -d "update=LOAD <http://web_server_private_ip:80/test.rdf>"
   ```

**nota**  
O uso de `SPARQL UPDATE LOAD` pode acionar um tempo limite no servidor da Web quando o arquivo de origem que está sendo carregado é grande. O Neptune processa os dados do arquivo à medida que são transmitidos, e, para um arquivo grande, isso pode demorar mais do que o tempo limite configurado no servidor. Isso, por sua vez, pode fazer com que o servidor feche a conexão, o que pode gerar a seguinte mensagem de erro quando o Neptune encontrar um EOF inesperado no fluxo:  

```
{
  "detailedMessage":"Invalid syntax in the specified file",
  "code":"InvalidParameterException"
}
```
Se receber essa mensagem e não acreditar que o arquivo de origem contenha uma sintaxe inválida, tente aumentar as definições de tempo limite no servidor da Web. Também é possível diagnosticar o problema ativando logs de depuração no servidor e procurando tempos limite.

# Usar o SPARQL UPDATE UNLOAD para excluir dados do Neptune
<a name="sparql-api-reference-unload"></a>

O Neptune também oferece uma operação SPARQL personalizada, `UNLOAD`, para remover dados especificados em uma fonte remota. `UNLOAD` pode ser considerado uma contrapartida da operação `LOAD`. A sintaxe é:

```
UNLOAD SILENT (URL of the remote data to be unloaded) FROM GRAPH (named graph from which to remove the data)
```
+ **`SILENT`**: (*opcional*) faz com que a operação seja bem-sucedida mesmo que tenha ocorrido um erro durante o processamento dos dados.

  Isso pode ser útil quando uma única transação contém várias declarações, como `"LOAD ...; LOAD ...; UNLOAD ...; LOAD ...;"` e você deseja que a transação seja concluída mesmo que alguns dos dados remotos não possam ser processados.
+ *URL of the remote data to be unloaded*— (*Obrigatório*) Especifica um arquivo de dados remoto contendo dados a serem descarregados de um gráfico.

  O arquivo remoto deve ter uma das seguintes extensões (são os mesmos formatos compatíveis com UPDATE-LOAD):
  + `.nt`para NTriples.
  + `.nq`para NQuads.
  + `.trig` para Trig.
  + `.rdf` para RDF/XML.
  + `.ttl` para Turtle.
  + `.n3` para N3.
  + `.jsonld` para JSON-LD.

  Todos os dados que esse arquivo contém serão removidos do cluster de banco de dados pela operação `UNLOAD`.

  Qualquer autenticação do Amazon S3 deve ser incluída no URL para que os dados sejam descarregados. É possível pré-assinar um arquivo do Amazon S3 e depois usar o URL resultante para acessá-lo com segurança. Por exemplo:

  ```
  aws s3 presign --expires-in (number of seconds) s3://(bucket name)/(path to file of data to unload)
  ```

  Em seguida:

  ```
  curl https://(a Neptune endpoint URL):8182/sparql \
    --data-urlencode 'update=unload (pre-signed URL of the remote Amazon S3 data to be unloaded) \
                             from graph (named graph)'
  ```

  Para obter mais informações, consulte [Autenticação de solicitações: usando parâmetros de consulta](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html).
+ **`FROM GRAPH `***(named graph from which to remove the data)*— (*Opcional*) Especifica o gráfico nomeado do qual os dados remotos devem ser descarregados.

  O Neptune associa cada triplo a um grafo nomeado. É possível especificar o grafo nomeado padrão usando o URI do grafo nomeado de fallback, `http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`, da seguinte forma:

  ```
  FROM GRAPH <http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph>
  ```

Da mesma forma que `LOAD` corresponde a `INSERT DATA { (inline data) }`, `UNLOAD` corresponde a `DELETE DATA { (inline data) }`. Como `DELETE DATA`, `UNLOAD` não funciona em dados com nós em branco.

Por exemplo, se um servidor web local fornecer um arquivo denominado `data.nt` que contenha estes dois triplos:

```
<http://example.org/resource#a> <http://example.org/resource#p> <http://example.org/resource#b> .
<http://example.org/resource#a> <http://example.org/resource#p> <http://example.org/resource#c> .
```

O seguinte comando `UNLOAD` excluirá esses dois triplos do grafo nomeado, `<http://example.org/graph1>`:

```
UNLOAD <http://localhost:80/data.nt> FROM GRAPH <http://example.org/graph1>
```

Isso terá o mesmo efeito que usar o seguinte comando `DELETE DATA`:

```
DELETE DATA {
  GRAPH <http://example.org/graph1> {
    <http://example.org/resource#a> <http://example.org/resource#p> <http://example.org/resource#b> .
    <http://example.org/resource#a> <http://example.org/resource#p> <http://example.org/resource#c> .
  }
}
```

**Exceções lançadas pelo comando `UNLOAD`.**
+ **`InvalidParameterException`**: havia nós em branco nos dados. *Status HTTP*: 400 Solicitação inválida.

  *Mensagem*: ` Blank nodes are not allowed for UNLOAD`

   
+ **`InvalidParameterException`**: havia uma sintaxe rompida nos dados. *Status HTTP*: 400 Solicitação inválida.

  *Mensagem*: `Invalid syntax in the specified file.`

   
+ **`UnloadUrlAccessDeniedException `**: acesso negado. *Status HTTP*: 400 Solicitação inválida.

  *Mensagem*: `Update failure: Endpoint (Neptune endpoint) reported access denied error. Please verify access.`

   
+ **`BadRequestException `**: os dados remotos não podem ser recuperados. *Status HTTP*: 400 Solicitação inválida.

  *Mensagem*: *(depende da resposta HTTP).*

# Dicas de consulta do SPARQL
<a name="sparql-query-hints"></a>

É possível usar as dicas de consulta para especificar estratégias de otimização e avaliação para uma determinada consulta SPARQL no Amazon Neptune. 

As dicas de consulta são expressas usando padrões triplos adicionais incorporados na consulta SPARQL com as seguintes partes:

```
scope hint value
```
+ *escopo*: determina a parte da consulta à qual a dica de consulta se aplica, como um grupo específico na consulta ou a consulta completa.
+ *dica*: identifica o tipo de dica a ser aplicada.
+ *value*: determina o comportamento do aspecto do sistema em consideração.

As dicas de consulta e os escopos são expostos como termos predefinidos no namespace `http://aws.amazon.com/neptune/vocab/v01/QueryHints#` do Amazon Neptune. Os exemplos desta seção incluem o namespace como um prefixo `hint` que é definido e incluído na consulta:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
```

O exemplo a seguir mostra como incluir uma dica `joinOrder` em uma consulta `SELECT`:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT ... {
 hint:Query hint:joinOrder "Ordered" .
 ...
}
```

A consulta anterior instrui o mecanismo do Neptune a avaliar junções na consulta em *determinada* ordem e desabilita qualquer reordenação automática.

Considere o seguinte ao usar as dicas de consulta:
+ É possível combinar dicas de consulta diferentes em uma única consulta. Por exemplo, é possível usar a dica de consulta `bottomUp` para anotar uma subconsulta para uma avaliação de baixo para cima e uma dica de consulta `joinOrder` para corrigir a ordem da junção dentro da subconsulta.
+ É possível usar a mesma dica de consulta várias vezes, em diferentes escopos não sobrepostos
+ Dicas de consultas são dicas. Embora o mecanismo de consulta geralmente tenha por objetivo considerar determinadas dicas de consulta, ele também pode ignorá-las.
+ As dicas de consulta são de preservação semântica. Adicionar uma dica de consulta não altera a saída da consulta (exceto pela possível ordem dos resultados quando nenhuma garantia de ordenação é oferecida, ou seja, quando a ordem dos resultados não é aplicada explicitamente usando ORDER BY). 

As seções a seguir fornecem mais informações sobre as dicas de consulta disponíveis e o uso no Neptune.

**Topics**
+ [Escopo de dicas de consulta do SPARQL no Neptune](#sparql-query-hints-scope)
+ [A dica de consulta `joinOrder` SPARQL](sparql-query-hints-joinOrder.md)
+ [A dica de consulta `evaluationStrategy` SPARQL](sparql-query-hints-evaluationStrategy.md)
+ [A dica de consulta `queryTimeout` SPARQL](sparql-query-hints-queryTimeout.md)
+ [A dica de consulta `rangeSafe` SPARQL](sparql-query-hints-rangeSafe.md)
+ [A dica de consulta `queryId` SPARQL](sparql-query-hints-queryId.md)
+ [A dica de consulta `useDFE` SPARQL](sparql-query-hints-useDFE.md)
+ [Dicas de consulta SPARQL usadas com DESCRIBE](sparql-query-hints-for-describe.md)

## Escopo de dicas de consulta do SPARQL no Neptune
<a name="sparql-query-hints-scope"></a>

A tabela a seguir mostra os escopos disponíveis, as dicas associadas e as descrições de dicas de consulta do SPARQL no Amazon Neptune. O prefixo `hint` nessas entradas representa o namespace do Neptune para dicas:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
```


| Escopo | Dica compatível | Description | 
| --- | --- | --- | 
| hint:Query | [joinOrder](sparql-query-hints-joinOrder.md) | A dica de consulta se aplica à consulta inteira. | 
| hint:Query | [queryTimeout](sparql-query-hints-queryTimeout.md) | O valor de tempo limite se aplica a toda a consulta. | 
| hint:Query | [rangeSafe](sparql-query-hints-rangeSafe.md) | A promoção de tipo está desabilitada para toda a consulta. | 
| hint:Query | [queryId](sparql-query-hints-queryId.md) | O valor de ID de consulta se aplica a toda a consulta. | 
| hint:Query | [useDFE](sparql-query-hints-useDFE.md) | O uso do DFE está habilitado (ou desabilitado) para toda a consulta. | 
| hint:Group | [joinOrder](sparql-query-hints-joinOrder.md) | A dica de consulta se aplica aos elementos de nível superior no grupo especificado, mas não a elementos aninhados (como as subconsultas) ou elementos pai. | 
| hint:SubQuery | [evaluationStrategy](sparql-query-hints-evaluationStrategy.md) | A dica é especificada e aplicada a uma subconsulta SELECT aninhada. A subconsulta é avaliada de maneira independente, sem considerar as soluções calculadas antes da subconsulta. | 

# A dica de consulta `joinOrder` SPARQL
<a name="sparql-query-hints-joinOrder"></a>

Quando você envia uma consulta do SPARQL, o mecanismo de consulta do Amazon Neptune investiga a estrutura da consulta. Ele reordena partes da consulta e tenta minimizar a quantidade de trabalho necessária para a avaliação e o tempo de resposta da consulta.

Por exemplo, uma sequência de padrões triplos conectados normalmente não é avaliada na ordem indicada. Ela é reordenada usando heurística e estatísticas, como a seletividade dos padrões individuais e como eles estão conectados por meio de variáveis compartilhadas. Além disso, se sua consulta contiver padrões mais complexos, como subconsultas ou blocos OPTIONAL ou MINUS complexos FILTERs, o mecanismo de consulta Neptune os reordenará sempre que possível, visando uma ordem de avaliação eficiente.

Para consultas mais complexas, a ordem que o Neptune escolhe para avaliar a consulta pode não ser sempre a ideal. Por exemplo, o Neptune pode perder características específicas de dados da instância (como atingir nós avançados no grafo) que surgem durante a avaliação da consulta.

Se você sabe exatamente as características dos dados e deseja ditar manualmente a ordem de execução da consulta, use a dica de consulta `joinOrder` do Neptune para especificar que a consulta deve ser avaliada na ordem indicada.

## Sintaxe de dica `joinOrder` SPARQL
<a name="sparql-query-hints-joinOrder-syntax"></a>

A dica de consulta `joinOrder` é especificada como um padrão triplo incluído em uma consulta SPARQL.

Para fins de clareza, a seguinte sintaxe usa um prefixo `hint` definido e incluído na consulta para especificar o namespace de dica de consulta do Neptune:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
scope hint:joinOrder "Ordered" .
```

**Escopos disponíveis**
+ `hint:Query`
+ `hint:Group`

Para obter mais informações sobre escopos de dica de consulta, consulte [Escopo de dicas de consulta do SPARQL no Neptune](sparql-query-hints.md#sparql-query-hints-scope).

## Exemplo de dica `joinOrder` SPARQL
<a name="sparql-query-hints-joinOrder-example"></a>

Esta seção mostra uma consulta gravada com e sem a dica de consulta `joinOrder` e otimizações relacionadas.

Para este exemplo, suponha que o conjunto de dados contenha o seguinte:
+ Uma única pessoa chamada `John` que curte (`:likes`) 1.000 pessoas, inclusive `Jane`.
+ Uma única pessoa chamada `Jane` que curte (`:likes`) 10 pessoas, inclusive `John`.

**Nenhuma dica de consulta**  
A seguinte consulta SPARQL extrai todos os pares de pessoas chamados `John` e `Jane` que curtem um ao outro de um conjunto de dados de redes sociais:

```
PREFIX : <https://example.com/>
SELECT ?john ?jane {
  ?person1 :name "Jane" .
  ?person1 :likes ?person2 .
  ?person2 :name "John" .
  ?person2 :likes ?person1 .
}
```

O mecanismo de consulta do Neptune pode avaliar as declarações em uma ordem diferente da escrita. Por exemplo, ele pode escolher avaliar na seguinte ordem:

1. Encontrar todas as pessoas chamadas `John`.

1. Encontrar todas as pessoas conectadas a `John` por uma borda `:likes`.

1. Filtrar esse conjunto por pessoas chamadas `Jane`.

1. Filtrar esse conjunto por aqueles indivíduos conectados a `John` por uma borda `:likes`.

De acordo com o conjunto de dados, avaliar nesta ordem resulta em 1.000 entidades sendo extraídas na segunda etapa. A terceira etapa restringe isso ao único nó, `Jane`. A etapa final determina que `Jane` também curte (`:likes`) o nó `John`.

**Dica de consulta**  
Seria favorável começar com o nó `Jane` porque ela tem apenas 10 bordas `:likes` de saída. Isso reduz a quantidade de trabalho durante a avaliação da consulta, evitando a extração de 1.000 entidades durante a segunda etapa.

O exemplo a seguir usa a consulta **joinOrder** para garantir que o nó `Jane` e suas bordas de saída sejam processados primeiro ao desabilitar toda a reordenação automática de junção da consulta:

```
PREFIX : <https://example.com/>
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT ?john ?jane {
  hint:Query hint:joinOrder "Ordered" .
  ?person1 :name "Jane" .
  ?person1 :likes ?person2 .
  ?person2 :name "John" .
  ?person2 :likes ?person1 .
}
```

Um cenário do mundo real aplicável pode ser um aplicativo de rede social no qual as pessoas na rede são classificadas tanto como influenciadoras com muitas conexões ou como usuários normais com poucas conexões. Em um cenário como esse, você pode garantir que o usuário normal (`Jane`) seja processado antes do influenciador (`John`) em uma consulta como o exemplo anterior.

**Dica de consulta e reordenação**  
Você pode levar este exemplo uma etapa adiante. Se você sabe que o atributo `:name` é exclusivo para um único nó, pode acelerar a consulta ao reorganizar e usar a dica de consulta `joinOrder`. Essa etapa garante que os nós exclusivos sejam extraídos primeiro.

```
PREFIX : <https://example.com/>
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT ?john ?jane {
  hint:Query hint:joinOrder "Ordered" .
  ?person1 :name "Jane" .
  ?person2 :name "John" .
  ?person1 :likes ?person2 .
  ?person2 :likes ?person1 .
}
```

Nesse caso, você pode reduzir a consulta às seguintes ações individuais em cada etapa:

1. Encontrar o nó de uma única pessoa com `:name` `Jane`.

1. Encontrar o nó de uma única pessoa com `:name` `John`.

1. Verificar se o primeiro nó está conectado ao segundo com uma borda `:likes`.

1. Verificar se o segundo nó está conectado ao primeiro com uma borda `:likes`.



**Importante**  
Se você escolher a ordem errada, a dica de consulta `joinOrder` poderá resultar em quedas de desempenho significativas. Por exemplo, o exemplo anterior seria ineficaz se os atributos `:name` não fossem exclusivos. Se todos os 100 nós fossem nomeados `Jane` e todos os 1.000 nós fossem nomeados `John`, a consulta terminaria verificando 1.000 \$1 100 (100.000) pares para bordas `:likes`.

# A dica de consulta `evaluationStrategy` SPARQL
<a name="sparql-query-hints-evaluationStrategy"></a>

A dica de consulta `evaluationStrategy` informa ao mecanismo de consulta do Amazon Neptune que o fragmento de consulta anotado deve ser avaliado de baixo para cima, como uma unidade independente. Isso significa que nenhuma solução das etapas anteriores da avaliação é usada para computar o fragmento de consulta. O fragmento de consulta é avaliado como uma unidade autônoma, e suas soluções produzidas são unidas ao restante da consulta após serem computadas.

Usar a dica de consulta `evaluationStrategy` implica em um bloqueio (sem pipeline) do plano de consulta, o que significa que as soluções do fragmento anotado com a dica de consulta são materializadas e armazenadas em buffer na memória principal. Usar essa dica de consulta pode aumentar significativamente a quantidade de memória principal necessária para avaliar a consulta, especialmente se o fragmento de consulta anotado calcula um grande número de resultados.

## Sintaxe de dica `evaluationStrategy` SPARQL
<a name="sparql-query-hints-evaluationStrategy-syntax"></a>

A dica de consulta `evaluationStrategy` é especificada como um padrão triplo incluído em uma consulta SPARQL.

Para fins de clareza, a seguinte sintaxe usa um prefixo `hint` definido e incluído na consulta para especificar o namespace de dica de consulta do Neptune:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
hint:SubQuery hint:evaluationStrategy "BottomUp" .
```

**Escopos disponíveis**
+ `hint:SubQuery`

**nota**  
Essa dica de consulta é compatível apenas com subconsultas aninhadas.

Para obter mais informações sobre escopos de dica de consulta, consulte [Escopo de dicas de consulta do SPARQL no Neptune](sparql-query-hints.md#sparql-query-hints-scope).

## Exemplo de dica `evaluationStrategy` SPARQL
<a name="sparql-query-hints-evaluationStrategy-example"></a>



Esta seção mostra uma consulta gravada com e sem a dica de consulta `evaluationStrategy` e otimizações relacionadas.

Para este exemplo, suponha que o dataset tenha as seguintes características:
+ Ele contém 1.000 pontos rotulados `:connectedTo`.
+ Cada nó `component` está conectado a uma média de 100 outros nós `component`.
+ O número típico de conexões cíclicas de quatro saltos entre nós é em torno de 100.

Como um exemplo típico, a dica `evaluationStrategy` pode ser útil para otimizar padrões de consulta contendo ciclos.

**Nenhuma dica de consulta**  
A seguinte consulta SPARQL extrai todos os nós `component` que estão ciclicamente conectados entre si por meio de quatro saltos:

```
PREFIX : <https://example.com/>
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT * {
  ?component1 :connectedTo ?component2 .
  ?component2 :connectedTo ?component3 .
  ?component3 :connectedTo ?component4 .
  ?component4 :connectedTo ?component1 .
}
```

A abordagem do mecanismo de consulta do Neptune é avaliar essa consulta usando as seguintes etapas:
+ Extrair todos os 1.000 pontos `connectedTo` no gráfico.
+ Expandir em 100x (o número de pontos de saída `connectedTo` de component2).

  Resultados intermediários: 100.000 nós.
+ Expandir em 100x (o número de pontos de saída `connectedTo` de component3).

  Resultados intermediários: 10.000.000 nós.
+ Examinar os 10.000.000 nós para o fechamento do ciclo.

Isso resulta em um plano de consulta de streaming, que tem uma quantidade constante de memória principal.

**Dica de consulta e subconsultas**  
Talvez você queira trocar o espaço da memória principal para computação acelerada. Ao reescrever a consulta usando uma dica de consulta `evaluationStrategy`, você pode forçar o mecanismo a calcular uma junção entre dois subconjuntos menores e materializados.

```
PREFIX : <https://example.com/>
          PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT * {
  {
    SELECT * WHERE {
      hint:SubQuery hint:evaluationStrategy "BottomUp" .
      ?component1 :connectedTo ?component2 .
      ?component2 :connectedTo ?component3 .
    }
  }
  {
    SELECT * WHERE {
      hint:SubQuery hint:evaluationStrategy "BottomUp" .
      ?component3 :connectedTo ?component4 .
      ?component4 :connectedTo ?component1 .
    }
  }
}
```

Em vez de avaliar os padrões triplos em sequência enquanto usa interativamente os resultados dos padrões interativos triplos anteriores como entrada para os próximos padrões, a dica `evaluationStrategy` faz com que duas subconsultas sejam avaliadas de forma independente. Ambas as subconsultas produzem 100.000 nós para os resultados intermediários, que são, por sua vez, unidos para formar a saída final. 

Especificamente, quando você executar o Neptune nos tipos de instância maiores, armazenar temporariamente esses dois subconjuntos de cem mil nós na memória principal aumentará o uso de memória em troca de acelerar significativamente a avaliação.

# A dica de consulta `queryTimeout` SPARQL
<a name="sparql-query-hints-queryTimeout"></a>

A dica de consulta `queryTimeout` especifica um tempo limite menor do que o valor `neptune_query_timeout` definido no grupo de parâmetros do banco de dados.

Se a consulta for encerrada como resultado dessa dica, um `TimeLimitExceededException` será lançado com uma mensagem `Operation terminated (deadline exceeded)`.

## Sintaxe de dica `queryTimeout` SPARQL
<a name="sparql-query-hints-queryTimeout-syntax"></a>

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT ... WHERE {
    hint:Query hint:queryTimeout 10 .
    # OR
    hint:Query hint:queryTimeout "10" .
    # OR
    hint:Query hint:queryTimeout "10"^^xsd:integer .
 ...
}
```

O valor de tempo limite é expresso em milissegundos.

O valor de tempo limite deve ser menor que o valor `neptune_query_timeout` definido no grupo de parâmetros de banco de dados. Caso contrário, uma exceção `MalformedQueryException` será gerada com uma mensagem `Malformed query: Query hint 'queryTimeout' must be less than neptune_query_timeout DB Parameter Group`.

A dica de consulta `queryTimeout` deve ser especificada na cláusula `WHERE` da consulta principal, ou na cláusula `WHERE` de uma das subconsultas, conforme mostrado no exemplo a seguir.

Ele deve ser definido somente uma vez em todas as queries/subqueries seções de atualizações do SPARQL (como INSERT e DELETE). Caso contrário, uma exceção `MalformedQueryException` será gerada com uma mensagem `Malformed query: Query hint 'queryTimeout' must be set only once`.

**Escopos disponíveis**

A dica `queryTimeout` pode ser aplicada a consultas e atualizações SPARQL.
+ Em uma consulta SPARQL, ela pode aparecer na cláusula WHERE da consulta principal ou em uma subconsulta.
+ Em uma atualização SPARQL, ela pode ser definida na cláusula INSERT, DELETE ou WHERE. Se houver várias cláusulas de atualização, ela só poderá ser definida em uma delas.

Para obter mais informações sobre escopos de dica de consulta, consulte [Escopo de dicas de consulta do SPARQL no Neptune](sparql-query-hints.md#sparql-query-hints-scope).

## Exemplo de dica `queryTimeout` SPARQL
<a name="sparql-query-hints-queryTimeout-example"></a>

Veja um exemplo de uso de `hint:queryTimeout` na cláusula principal `WHERE` de uma consulta `UPDATE`:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
INSERT {
    ?s ?p ?o
} WHERE {
    hint:Query hint:queryTimeout 100 .
    ?s ?p ?o .
}
```

Aqui, `hint:queryTimeout` está na cláusula `WHERE` de uma subconsulta:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT * {
   ?s ?p ?o .
   {
      SELECT ?s WHERE {
         hint:Query hint:queryTimeout 100 .
         ?s ?p1 ?o1 .
      }
   }
}
```

# A dica de consulta `rangeSafe` SPARQL
<a name="sparql-query-hints-rangeSafe"></a>

Use essa dica de consulta para desativar a promoção de tipo para uma consulta SPARQL.

Quando você envia uma consulta do SPARQL que inclua um `FILTER` por um intervalo ou um valor numérico, o mecanismo de consulta do Neptune normalmente deve usar promoção de tipo ao executar a consulta. Isso significa que ele precisa examinar valores de todos os tipos que possam conter o valor que você está filtrando.

Por exemplo, se você estiver filtrando valores iguais a 55, o mecanismo deverá procurar números inteiros iguais a 55, números inteiros longos iguais a 55L, flutuantes iguais a 55,0, etc. Cada promoção de tipo exige uma pesquisa adicional no armazenamento, o que pode fazer com que uma consulta aparentemente simples leve um tempo inesperadamente longo para ser concluída.

Muitas vezes, a promoção de tipo é desnecessária porque você sabe de antemão que só precisa encontrar valores de um tipo específico. Nesse caso, você pode acelerar suas consultas drasticamente usando a dica de consulta `rangeSafe` para desativar a promoção de tipos.

## Sintaxe de dica `rangeSafe` SPARQL
<a name="sparql-query-hints-rangeSafe-syntax"></a>

A dica de consulta `rangeSafe` assume o valor `true` para desativar a promoção de tipo. Ela também aceita o valor `false` (o padrão).

**Exemplo.** O seguinte exemplo mostra como desativar a promoção de tipo ao filtrar por um valor inteiro `o` maior que 1:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT * {
   ?s ?p ?o .
   hint:Prior hint:rangeSafe 'true' .
   FILTER (?o > '1'^^<http://www.w3.org/2001/XMLSchema#int>)
```

# A dica de consulta `queryId` SPARQL
<a name="sparql-query-hints-queryId"></a>

Use esta dica de consulta para atribuir seu próprio valor de queryId a uma consulta SPARQL.

Exemplo:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
SELECT * WHERE {
  hint:Query hint:queryId "4d5c4fae-aa30-41cf-9e1f-91e6b7dd6f47"
  {?s ?p ?o}}
```

O valor atribuído deve ser exclusivo em todas as consultas no banco de dados do Neptune.

# A dica de consulta `useDFE` SPARQL
<a name="sparql-query-hints-useDFE"></a>

Use essa dica de consulta para permitir o uso do DFE para executar a consulta. Por padrão, o Neptune não usa o DFE sem que essa dica de consulta esteja definida como `true`, porque o parâmetro de instância [neptune\$1dfe\$1query\$1engine](parameters.md#parameters-instance-parameters-neptune_dfe_query_engine) tem como padrão `viaQueryHint`. Se você definir esse parâmetro de instância como `enabled`, o mecanismo do DFE será usado para todas as consultas, exceto aquelas com a dica de consulta `useDFE` definida como `false`.

Exemplo de habilitação do uso do DFE para uma consulta:

```
PREFIX : <https://example.com/>
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>

SELECT ?john ?jane
{
  hint:Query hint:useDFE true .
  ?person1 :name "Jane" .
  ?person1 :likes ?person2 .
  ?person2 :name "John" .
  ?person2 :likes ?person1 .
}
```

# Dicas de consulta SPARQL usadas com DESCRIBE
<a name="sparql-query-hints-for-describe"></a>

Uma consulta `DESCRIBE` SPARQL oferece um mecanismo flexível para solicitar descrições de recursos. No entanto, as especificações do SPARQL não definem a semântica precisa de `DESCRIBE`.

A partir da [versão 1.2.0.2 do mecanismo](engine-releases-1.2.0.2.md), o Neptune é compatível com vários modos `DESCRIBE` e algoritmos diferentes que são adequados para situações diferentes.

Esse exemplo de conjunto de dados pode ajudar a ilustrar os diferentes modos:

```
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <https://example.com/> .

:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JohnDoe :firstName "John" .
:JaneDoe :knows _:b1 .
_:b1 :knows :RichardRoe .

:RichardRoe :knows :JaneDoe .
:RichardRoe :firstName "Richard" .

_:s1 rdf:type rdf:Statement .
_:s1 rdf:subject :JaneDoe .
_:s1 rdf:predicate :knows .
_:s1 rdf:object :JohnDoe .
_:s1 :knowsFrom "Berlin" .

:ref_s2 rdf:type rdf:Statement .
:ref_s2 rdf:subject :JaneDoe .
:ref_s2 rdf:predicate :knows .
:ref_s2 rdf:object :JohnDoe .
:ref_s2 :knowsSince 1988 .
```

Os exemplos abaixo pressupõem que uma descrição do recurso `:JaneDoe` está sendo solicitada usando uma consulta SPARQL como esta:

```
DESCRIBE <https://example.com/JaneDoe>
```

## A dica de consulta `describeMode` SPARQL
<a name="sparql-query-hints-describeMode"></a>

A dica de consulta `hint:describeMode` SPARQL é usada para selecionar um dos seguintes modos `DESCRIBE` SPARQL compatíveis com o Neptune:

### O modo `ForwardOneStep` DESCRIBE
<a name="sparql-query-hints-describeMode-ForwardOneStep"></a>

Você invoca o modo `ForwardOneStep` com a dica de consulta `describeMode` desta forma:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "ForwardOneStep"
}
```

O modo `ForwardOneStep` gera somente os atributos e os links diretos do recurso a ser descrito. No caso de exemplo, isso significa que ele gera os triplos que têm `:JaneDoe`, o recurso a ser descrito, como assunto:

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b301990159 .
```

Observe que a consulta DESCRIBE pode retornar triplas com nós em branco, como`_:b301990159`, que são diferentes a IDs cada vez, em comparação com o conjunto de dados de entrada.

### O modo `SymmetricOneStep` DESCRIBE
<a name="sparql-query-hints-describeMode-SymmetricOneStep"></a>

`SymmetricOneStep` é o modo DESCRIBE padrão caso você não forneça uma dica de consulta. Você também pode invocá-la explicitamente com uma dica de consulta `describeMode` da seguinte forma:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "SymmetricOneStep"
}
```

Na semântica `SymmetricOneStep`, `DESCRIBE` retorna os atributos, links diretos e links reversos do recurso a ser descrito:

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b318767375 .

_:b318767631 rdf:subject :JaneDoe .

:RichardRoe :knows :JaneDoe .

:ref_s2 rdf:subject :JaneDoe .
```

### O modo Concise Bounded Description (`CBD`) DESCRIBE
<a name="sparql-query-hints-describeMode-CBD"></a>

O modo Concise Bounded Description (`CBD`) é invocado usando a dica de consulta `describeMode` da seguinte forma:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "CBD"
}
```

Na semântica `CBD`, `DESCRIBE` gera o modo Concise Bounded Description (conforme [definido pelo W3C](http://www.w3.org/Submission/CBD)) do recurso a ser descrito:

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b285212943 .
_:b285212943 :knows :RichardRoe .

_:b285213199 rdf:subject :JaneDoe .
_:b285213199 rdf:type rdf:Statement .
_:b285213199 rdf:predicate :knows .
_:b285213199 rdf:object :JohnDoe .
_:b285213199 :knowsFrom "Berlin" .

:ref_s2 rdf:subject :JaneDoe .
```

O modo Concise Bounded Description de um recurso do RDF (ou seja, um nó em um grafo do RDF) é o menor subgrafo centralizado em torno desse nó que pode ficar independente. Na prática, isso significa que, se você pensar nesse grafo como uma árvore, com o nó designado como raiz, não haverá nós em branco (nós) como folhas dessa árvore. Como os nós não podem ser tratados externamente nem usados em consultas subsequentes, não basta navegar no grafo apenas para encontrar os próximos saltos únicos do nó atual. Você também precisa ir longe o suficiente para encontrar algo que possa ser usado em consultas subsequentes (ou seja, algo diferente de um bnode).

#### Calcular o CBD
<a name="sparql-query-hints-describeMode-CBD-computing"></a>

Dado um nó específico (o nó inicial ou raiz) no grafo do RDF de origem, o CBD desse nó é calculado da seguinte forma:

1. Inclua no subgrafo todas as declarações no grafo de origem em que o *assunto* da declaração é o nó inicial.

1. Recursivamente, até o momento, para todas as declarações no subgrafo que têm um *objeto* de nó em branco, inclua no subgrafo todas as declarações no grafo de origem em que o *assunto* da declaração seja esse nó em branco e que ainda não tenham sido incluídas no subgrafo.

1. Recursivamente, até o momento, para todas as declarações incluídas no subgrafo, para todas as reificações dessas declarações no grafo de origem, inclua o CBD começando no nó `rdf:Statement` de cada retificação.

Isso gera um subgrafo em que os nós do *objeto* são referências ou literais do IRI, ou nós em branco que não servem como *assunto* de nenhuma declaração no grafo. Observe que o CBD não pode ser calculado usando uma única consulta SPARQL SELECT ou CONSTRUCT.

### O modo Symmetric Concise Bounded Description (`SCBD`) DESCRIBE
<a name="sparql-query-hints-describeMode-SCBD"></a>

O modo Symmetric Concise Bounded Description (`SCBD`) é invocado usando a dica de consulta `describeMode` da seguinte forma:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "SCBD"
}
```

Na semântica `SCBD`, `DESCRIBE` gera o modo Symmetric Concise Bounded Description do recurso (conforme definido pelo W3C em [Describing Linked Datasets with the VoID Vocabulary](http://www.w3.org/TR/void/):

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b335544591 .
_:b335544591 :knows :RichardRoe .

:RichardRoe :knows :JaneDoe .

_:b335544847 rdf:subject :JaneDoe .
_:b335544847 rdf:type rdf:Statement .
_:b335544847 rdf:predicate :knows .
_:b335544847 rdf:object :JohnDoe .
_:b335544847 :knowsFrom "Berlin" .

:ref_s2 rdf:subject :JaneDoe .
```

A vantagem do CBD e do SCBD em relação aos modos `ForwardOneStep` e `SymmetricOneStep` é que os nós em branco são sempre expandidos para incluir a respectiva representação. Isso pode ser uma vantagem importante porque não é possível consultar um nó em branco usando o SPARQL. Além disso, os modos CBD e SCBD também consideram as reificações.

Observe que a dica de consulta `describeMode` também pode fazer parte de uma cláusula `WHERE`:

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE ?s
WHERE {
  hint:Query hint:describeMode "CBD" .
  ?s rdf:type <https://example.com/Person>
}
```

## A dica de consulta `describeIterationLimit` SPARQL
<a name="sparql-query-hints-describeIterationLimit"></a>

A dica de consulta `hint:describeIterationLimit` SPARQL fornece uma restrição **opcional** sobre o número máximo de expansões iterativas a serem executadas para algoritmos DESCRIBE iterativos, como CBD e SCBD.

Os limites do DESCRIBE estão ANDed juntos. Portanto, se o limite de iteração e o limite de declarações forem especificados, os dois limites deverão ser atendidos antes que a consulta DESCRIBE seja eliminada.

O padrão para esse valor é cinco. Você pode defini-lo como ZERO (0) para especificar SEM limite no número de expansões iterativas.

## A dica de consulta `describeStatementLimit` SPARQL
<a name="sparql-query-hints-describeStatementLimit"></a>

A dica de consulta `hint:describeStatementLimit` SPARQL fornece uma restrição **opcional** sobre o número máximo de declarações que podem estar presentes em uma resposta de consulta DESCRIBE. Ele é aplicado apenas para algoritmos DESCRIBE iterativos, como CBD e SCBD.

Os limites do DESCRIBE estão ANDed juntos. Portanto, se o limite de iteração e o limite de declarações forem especificados, os dois limites deverão ser atendidos antes que a consulta DESCRIBE seja eliminada.

O padrão para esse valor é cinco mil. Você pode defini-lo como ZERO (0) para especificar SEM limite no número de declarações geradas.

# Comportamento do SPARQL DESCRIBE em relação ao grafo padrão
<a name="sparql-default-describe"></a>

O formato da consulta [https://www.w3.org/TR/sparql11-query/#describe](https://www.w3.org/TR/sparql11-query/#describe) SPARQL permite que você recupere informações sobre recursos sem conhecer a estrutura dos dados e sem precisar compor uma consulta. A forma como essas informações são reunidas é deixada para a implementação do SPARQL. O Neptune fornece [várias dicas de consulta](sparql-query-hints-for-describe.md) que invocam diferentes modos e algoritmos para `DESCRIBE` usar.

Na implementação do Neptune, independentemente do modo, `DESCRIBE` usa apenas dados presentes no [grafo padrão do SPARQL](feature-sparql-compliance.md#sparql-default-graph). Isso é consistente com a forma como o SPARQL trata os conjuntos de dados (consulte [Specifying RDF Datasets](https://www.w3.org/TR/sparql11-query/#specifyingDataset) na especificação do SPARQL).

Em Neptune, o gráfico padrão contém todos os triplos exclusivos na união de todos os gráficos nomeados no banco de dados, a menos que gráficos nomeados específicos sejam especificados usando cláusulas. `FROM` and/or `FROM NAMED` Todos os dados do RDF no Neptune são armazenados em um grafo nomeado. Se um triplo for inserido sem um contexto de grafo nomeado, o Neptune o armazenará em um grafo nomeado designado `http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`.

Quando um ou mais grafos nomeados são especificados usando a cláusula `FROM`, o grafo padrão é a união de todos os triplos exclusivos nesses grafos nomeados. Se não houver nenhuma cláusula `FROM` e houver uma ou mais cláusulas `FROM NAMED`, o grafo padrão estará em branco.

## Exemplos de `DESCRIBE` do SPARQL
<a name="sparql-default-describe-examples"></a>

Pense nos seguintes dados:

```
PREFIX ex: <https://example.com/>

GRAPH ex:g1 {
    ex:s ex:p1 "a" .
    ex:s ex:p2 "c" .
}

GRAPH ex:g2 {
    ex:s ex:p3 "b" .
    ex:s ex:p2 "c" .
}

ex:s ex:p3 "d" .
```

Para essa consulta:

```
PREFIX ex: <https://example.com/>
DESCRIBE ?s
FROM ex:g1
FROM NAMED ex:g2
WHERE {
  GRAPH ex:g2 { ?s ?p "b" . }
}
```

O Neptune geraria:

```
ex:s ex:p1 "a" .
ex:s ex:p2 "c" .
```

Aqui, o padrão do grafo `GRAPH ex:g2 { ?s ?p "b" }` é avaliado primeiro, gerando vinculações para `?s` e, depois, a parte `DESCRIBE` é avaliada sobre o grafo padrão, que agora é apenas `ex:g1`.

No entanto, para essa consulta:

```
PREFIX ex: <https://example.com/>
DESCRIBE ?s 
FROM NAMED ex:g1 
WHERE { 
  GRAPH ex:g1 { ?s ?p "a" . } 
}
```

O Neptune não geraria nada, porque quando uma cláusula `FROM NAMED` está presente sem nenhuma cláusula `FROM`, o grafo padrão está em branco.

Na seguinte consulta, `DESCRIBE` é usado sem as cláusulas `FROM` ou `FROM NAMED`presentes:

```
PREFIX ex: <https://example.com/>
DESCRIBE ?s 
WHERE { 
  GRAPH ex:g1 { ?s ?p "a" . } 
}
```

Nessa situação, o grafo padrão é composto por todos os triplos exclusivos na união de todos os grafos nomeados no banco de dados (formalmente, a mesclagem do RDF), então o Neptune geraria:

```
ex:s ex:p1 "a" . 
ex:s ex:p2 "c" . 
ex:s ex:p3 "b" .
ex:s ex:p3 "d" .
```

# API de status de consulta do SPARQL
<a name="sparql-api-status"></a>

Para obter o status das consultas SPARQL, use HTTP `GET` ou `POST` para fazer uma solicitação ao endpoint de `https://your-neptune-endpoint:port/sparql/status`. 

## Parâmetros de solicitação do status de consulta do SPARQL
<a name="sparql-api-status-get-request"></a>

**queryId (opcional)**  
O ID de uma consulta SPARQL em execução. Exibe apenas o status da consulta especificada.

## Sintaxe da resposta do status de consulta do SPARQL
<a name="sparql-api-status-get-response-syntax"></a>

```
{
    "acceptedQueryCount": integer,
    "runningQueryCount": integer,
    "queries": [
      {
        "queryId":"guid",
        "queryEvalStats":
          {
            "subqueries": integer,
            "elapsed": integer,
            "cancelled": boolean
          },
        "queryString": "string"
      }
    ]
}
```

## Valores da resposta do status de consulta do SPARQL
<a name="sparql-api-status-get-response-values"></a>

**acceptedQueryCount**  
O número de consultas aceitas desde o último reinício do mecanismo do Neptune.

**runningQueryCount**  
O número de consultas SPARQL em execução atualmente.

**queries**  
Uma lista de consultas SPARQL atuais.

**queryId**  
Um ID de GUID da consulta. O Neptune atribui automaticamente esse valor de ID a cada consulta, ou você também pode atribuir seu próprio ID (consulte [Injetar um ID personalizado em uma consulta do Gremlin ou do SPARQL no Neptune](features-query-id.md)). 

**queryEvalStats**  
Estatísticas dessa consulta.

**subconsultas**  
Número de subconsultas nesta consulta.

**elapsed**  
O número de milissegundos em que a consulta esteve em execução até agora.

**cancelado**  
Verdadeiro indica que a consulta foi cancelada.

**queryString**  
A consulta enviada.

## Exemplo de status de consulta do SPARQL
<a name="sparql-api-status-get-example"></a>

A seguir está um exemplo de comando de status usando `curl` e HTTP `GET`.

```
curl https://your-neptune-endpoint:port/sparql/status
```

Essa saída mostra uma única consulta em execução.

```
{
    "acceptedQueryCount":9,
    "runningQueryCount":1,
    "queries": [
        {
            "queryId":"fb34cd3e-f37c-4d12-9cf2-03bb741bf54f",
            "queryEvalStats":
                {
                    "subqueries": 0,
                    "elapsed": 29256,
                    "cancelled": false
                },
            "queryString": "SELECT ?s ?p ?o WHERE {?s ?p ?o}"
        }
    ]
}
```

# Cancelamento de consulta do SPARQL
<a name="sparql-api-status-cancel"></a>

Para obter o status das consultas SPARQL, use HTTP `GET` ou `POST` para fazer uma solicitação ao endpoint de `https://your-neptune-endpoint:port/sparql/status`.

## Parâmetros de solicitação do cancelamento da consulta do SPARQL
<a name="sparql-api-status-cancel-request"></a>

**cancelQuery**  
(Obrigatório) Ordena ao comando de status para cancelar uma consulta. Esse parâmetro não usa um valor.

**queryId**  
(Obrigatório) O ID da consulta SPARQL em execução a ser cancelada.

**silent**  
(Opcional) Se `silent=true`, a consulta em execução será cancelada e o código de resposta HTTP será 200. Se `silent` não estiver presente ou `silent=false`, a consulta será cancelada com um código de status HTTP 500.

## Exemplos de cancelamento de consultas do SPARQL
<a name="sparql-api-status-cancel-example"></a>

**Exemplo 1: cancelamento com `silent=false`**  
Veja a seguir um exemplo do comando de status que usa `curl` para cancelar uma consulta com o parâmetro `silent` definido como `false`:

```
curl https://your-neptune-endpoint:port/sparql/status \
  -d "cancelQuery" \
  -d "queryId=4d5c4fae-aa30-41cf-9e1f-91e6b7dd6f47" \
  -d "silent=false"
```

A menos que a consulta já tenha iniciado os resultados de streaming, a consulta cancelada retornaria um código HTTP 500 com uma resposta como esta:

```
{
  "code": "CancelledByUserException",
  "requestId": "4d5c4fae-aa30-41cf-9e1f-91e6b7dd6f47",
  "detailedMessage": "Operation terminated (cancelled by user)"
}
```

Se a consulta já retornou um código HTTP 200 (OK) e iniciou os resultados de streaming antes de ser cancelada, as informações de exceção de tempo limite serão enviadas para o fluxo de saída normal.

**Exemplo 2: cancelamento com `silent=true`**  
Veja a seguir um exemplo do mesmo comando de status acima, com a exceção de que o parâmetro `silent` agora está definido como `true`:

```
curl https://your-neptune-endpoint:port/sparql/status \
  -d "cancelQuery" \
  -d "queryId=4d5c4fae-aa30-41cf-9e1f-91e6b7dd6f47" \
  -d "silent=true"
```

Esse comando retornaria a mesma resposta de quando `silent=false`, mas a consulta cancelada agora retornaria um código HTTP 200 com uma resposta como esta:

```
{
  "head" : {
    "vars" : [ "s", "p", "o" ]
  },
  "results" : {
    "bindings" : [ ]
  }
}
```

# Usar o protocolo HTTP do SPARQL 1.1 Graph Store (GSP) no Amazon Neptune
<a name="sparql-graph-store-protocol"></a>

Na recomendação [SPARQL 1.1 Graph Store HTTP Protocol](https://www.w3.org/TR/sparql11-http-rdf-update/), o W3C definiu um protocolo HTTP para gerenciar grafos do RDF. Ele define operações para remover, criar e substituir o conteúdo do grafo do RDF, bem como para adicionar declarações do RDF ao conteúdo existente.

O protocolo de armazenamento de grafos (GSP) oferece uma maneira conveniente de manipular todo o grafo sem precisar escrever consultas do SPARQL complexas.

O Neptune suporta totalmente esse protocolo.

O endpoint do protocolo de armazenamento de grafos (GSP) é:

```
https://your-neptune-cluster:port/sparql/gsp/
```

Para acessar o grafo padrão com o GSP, use:

```
https://your-neptune-cluster:port/sparql/gsp/?default
```

Para acessar um grafo nomeado com o GSP, use:

```
https://your-neptune-cluster:port/sparql/gsp/?graph=named-graph-URI
```

## Detalhes especiais da implementação do GSP no Neptune
<a name="sparql-graph-store-protocol-special"></a>

O Neptune implementa totalmente a [recomendação do W3C](https://www.w3.org/TR/sparql11-http-rdf-update/) que define o GSP. No entanto, há algumas situações que a especificação não abrange.

Uma delas é o caso em que uma solicitação `PUT` ou `POST` especifica um ou mais grafos nomeados no corpo da solicitação que diferem do grafo especificado pelo URL da solicitação. Isso só pode acontecer quando o formato RDF do corpo da solicitação é compatível com grafos nomeados, por exemplo, usando `Content-Type: application/n-quads` ou `Content-Type: application/trig`.

Nessa situação, o Neptune adiciona ou atualiza todos os grafos nomeados presentes no corpo, bem como o grafo nomeado especificado no URL.

Por exemplo, suponha que, começando com um banco de dados vazio, você envie uma solicitação `PUT` para inverter os votos em três grafos. Um, denominado `urn:votes`, contém todos os votos de todos os anos eleitorais. Outros dois, denominados `urn:votes:2005` e `urn:votes:2019`, contêm votos de anos eleitorais específicos. A solicitação e sua carga útil têm a seguinte aparência:

```
PUT "http://your-Neptune-cluster:port/sparql/gsp/?graph=urn:votes"
  Host: example.com
  Content-Type: application/n-quads

  PAYLOAD:

  <urn:JohnDoe> <urn:votedFor> <urn:Labour> <urn:votes:2005>
  <urn:JohnDoe> <urn:votedFor> <urn:Conservative> <urn:votes:2019>
  <urn:JaneSmith> <urn:votedFor> <urn:LiberalDemocrats> <urn:votes:2005>
  <urn:JaneSmith> <urn:votedFor> <urn:Conservative> <urn:votes:2019>
```

Depois que a solicitação é executada, os dados no banco de dados ficam desta forma:

```
<urn:JohnDoe>   <urn:votedFor> <urn:Labour>           <urn:votes:2005>
<urn:JohnDoe>   <urn:votedFor> <urn:Conservative>     <urn:votes:2019>
<urn:JaneSmith> <urn:votedFor> <urn:LiberalDemocrats> <urn:votes:2005>
<urn:JaneSmith> <urn:votedFor> <urn:Conservative>     <urn:votes:2019>
<urn:JohnDoe>   <urn:votedFor> <urn:Labour>           <urn:votes>
<urn:JohnDoe>   <urn:votedFor> <urn:Conservative>     <urn:votes>
<urn:JaneSmith> <urn:votedFor> <urn:LiberalDemocrats> <urn:votes>
<urn:JaneSmith> <urn:votedFor> <urn:Conservative>     <urn:votes>
```

Outra situação ambígua é quando mais de um grafo é especificado no próprio URL da solicitação, usando qualquer um de `PUT`, `POST`, `GET` ou `DELETE`. Por exemplo:

```
POST "http://your-Neptune-cluster:port/sparql/gsp/?graph=urn:votes:2005&graph=urn:votes:2019"
```

Ou:

```
GET "http://your-Neptune-cluster:port/sparql/gsp/?default&graph=urn:votes:2019"
```

Nessa situação, o Neptune gera um HTTP 400 com uma mensagem indicando que somente um grafo pode ser especificado no URL da solicitação.

# Analisar a execução de consulta do Neptune usando o `explain` do SPARQL
<a name="sparql-explain"></a>

O Amazon Neptune adicionou um atributo do SPARQL denominado *explain*. Esse atributo é uma ferramenta de autoatendimento para compreender a abordagem da execução realizada pelo mecanismo do Neptune. Você o invoca adicionando um parâmetro `explain` a uma chamada HTTP que envia uma consulta do SPARQL.

O recurso `explain` fornece informações sobre a estrutura lógica dos planos de execução da consulta. Você pode usar essas informações para identificar possíveis gargalos de execução e de avaliação. Você pode usar as [dicas de consulta](sparql-query-hints.md) para melhorar os planos de execução de suas consultas.

**Topics**
+ [Como o mecanismo de consulta do SPARQL funciona no Neptune](sparql-explain-engine.md)
+ [Como usar o `explain` do SPARQL para analisar a execução de consultas do Neptune](sparql-explain-using.md)
+ [Exemplos de invocação do SPARQL `explain` no Neptune](sparql-explain-examples.md)
+ [Operadores SPARQL `explain` no Neptune](sparql-explain-operators.md)
+ [Limitações do SPARQL `explain` no Neptune](sparql-explain-limitations.md)

# Como o mecanismo de consulta do SPARQL funciona no Neptune
<a name="sparql-explain-engine"></a>

Para usar as informações que o atributo `explain` do SPARQL fornece, você precisa compreender alguns detalhes sobre como o mecanismo de consulta do SPARQL funciona no Amazon Neptune.

O mecanismo converte cada consulta do SPARQL em um pipeline de operadores. A partir do primeiro operador, soluções intermediárias conhecidas como *listas de associações* fluem por meio desse pipeline de operadores. Você pode considerar uma lista de associações como uma tabela na qual os cabeçalhos da tabela são um subconjunto das variáveis usadas na consulta. Cada linha da tabela representa um resultado, até o ponto de avaliação.

Vamos supor que dois prefixos de namespace foram definidos para nossos dados:

```
  @prefix ex:   <http://example.com> .
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
```

Veja a seguir um exemplo de uma lista de associações simples nesse contexto:

```
  ?person       | ?firstName
  ------------------------------------------------------
  ex:JaneDoe    | "Jane"
  ex:JohnDoe    | "John"
  ex:RichardRoe | "Richard"
```

Para cada uma das três pessoas, a lista vincula a variável `?person` a um identificador da pessoa, e a variável `?firstName` ao nome da pessoa.

Em geral, as variáveis poderão permanecer desvinculadas, se, por exemplo, houver uma seleção `OPTIONAL` de uma variável em uma consulta para a qual nenhum valor está presente nos dados.

O operador `PipelineJoin` é um exemplo de mecanismo de consulta do Neptune presente na saída de `explain`. Ele utiliza um conjunto de associações de entrada do operador anterior e junta isso a um padrão triplo, digamos `(?person, foaf:lastName, ?lastName)`. Esta operação usa as associações da variável `?person` em seu fluxo de entrada, substitui-as no padrão triplo e procura triplos no banco de dados.

Quando executado no contexto de associações de entrada da tabela anterior, o `PipelineJoin` deve avaliar três pesquisas, ou seja, o seguinte:

```
  (ex:JaneDoe,    foaf:lastName, ?lastName)
  (ex:JohnDoe,    foaf:lastName, ?lastName)
  (ex:RichardRoe, foaf:lastName, ?lastName)
```

Essa abordagem é chamada de avaliação *as-bound*. As soluções desse processo de avaliação são juntadas de volta com as soluções de entrada, preenchendo o `?lastName` detectado nas soluções de entrada. Supondo-se que você encontre um sobrenome para todas as três pessoas, o operador deve produzir uma lista de associações de saída que será semelhante à seguinte:

```
  ?person       | ?firstName | ?lastName
  ---------------------------------------
  ex:JaneDoe    | "Jane"     | "Doe"
  ex:JohnDoe    | "John"     | "Doe"
  ex:RichardRoe | "Richard"  | "Roe"
```

Essa lista de associações de saída serve, então, como entrada para o próximo operador no pipeline. No final, a saída do último operador no pipeline define o resultado da consulta.

Com frequência, os pipelines de operadores são lineares, no sentido de que cada operador emite soluções para um único operador conectado. No entanto, em alguns casos, eles podem ter estruturas mais complexas. Por exemplo, um operador `UNION` em uma consulta do SPARQL é mapeado para uma operação `Copy`. Essa operação duplica as associações e encaminha as cópias para dois subplanos, uma para o lado esquerdo e a outra para o lado direito da `UNION`.

Para obter mais informações sobre operadores, consulte [Operadores SPARQL `explain` no Neptune](sparql-explain-operators.md).

# Como usar o `explain` do SPARQL para analisar a execução de consultas do Neptune
<a name="sparql-explain-using"></a>

O atributo `explain` do SPARQL é uma ferramenta de autoatendimento no Amazon Neptune que ajuda a compreender a abordagem da execução realizada pelo mecanismo do Neptune. Para invocar o `explain`, você passa um parâmetro para uma solicitação HTTP ou HTTPS no formulário `explain=mode`.

O valor do modo pode ser `static`, `dynamic` ou `details`:
+ No modo *estático*, o `explain` imprime somente a estrutura estática do plano de consulta.
+ No modo *dynamic*, o `explain` também inclui aspectos dinâmicos do plano de consulta. Esses aspectos podem incluir o número de associações intermediárias que fluem por meio dos operadores, a proporção de associações de entrada para associações de saída e o tempo total utilizado pelos operadores.
+ No modo de *detalhes*, `explain` imprime as informações mostradas no modo `dynamic` mais detalhes adicionais, como a string de consulta SPARQL real e a contagem de intervalo estimada para o padrão subjacente a um operador de junção.

O Neptune é compatível com o uso do `explain` com todos os três protocolos de acesso de consulta do SPARQL listados na especificação [W3C SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/#query-operation), ou seja:

1. HTTP GET

1. HTTP POST usando parâmetros codificados por URL

1. HTTP POST usando parâmetros de texto

Para obter informações sobre o mecanismo de consulta do SPARQL, consulte [Como o mecanismo de consulta do SPARQL funciona no Neptune](sparql-explain-engine.md).

Para obter informações sobre o tipo de saída produzido ao invocar o `explain` do SPARQL, consulte [Exemplos de invocação do SPARQL `explain` no Neptune](sparql-explain-examples.md).

# Exemplos de invocação do SPARQL `explain` no Neptune
<a name="sparql-explain-examples"></a>

Os exemplos desta seção mostram os vários tipos de saída que você pode produzir ao invocar o atributo `explain` do SPARQL para analisar a execução de consultas no Amazon Neptune.

**Topics**
+ [Compreensão da saída do explain](#sparql-explain-example-output)
+ [Exemplo de saída do modo de detalhes](#sparql-explain-example-details)
+ [Exemplo de saída de modo estático](#sparql-explain-example-static)
+ [Diferentes formas de codificar parâmetros](#sparql-explain-example-parameters)
+ [Outros tipos de saída além de texto/sem formatação](#sparql-explain-output-options)
+ [Exemplo de saída de `explain` SPARQL quando o DFE está habilitado](#sparql-explain-output-dfe)

## Compreensão da saída do explain
<a name="sparql-explain-example-output"></a>

Neste exemplo, Jane Doe conhece duas pessoas, ou seja, John Doe e Richard Roe:

```
@prefix ex: <http://example.com> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

ex:JaneDoe foaf:knows ex:JohnDoe .
ex:JohnDoe foaf:firstName "John" .
ex:JohnDoe foaf:lastName "Doe" .
ex:JaneDoe foaf:knows ex:RichardRoe .
ex:RichardRoe foaf:firstName "Richard" .
ex:RichardRoe foaf:lastName "Roe" .
.
```

Para determinar os primeiros nomes de todas as pessoas que Jane Doe conhece, você pode escrever a seguinte consulta:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=PREFIX foaf: <https://xmlns.com/foaf/0.1/> PREFIX ex: <https://www.example.com/> \
       SELECT ?firstName WHERE { ex:JaneDoe foaf:knows ?person . ?person foaf:firstName ?firstName }" \
   -H "Accept: text/csv"
```

Esta consulta simples retorna o seguinte resultado:

```
firstName
John
Richard
```

Depois, altere o comando `curl` para invocar o `explain` adicionando `-d "explain=dynamic"` e usando o tipo de saída padrão em vez de `text/csv`:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=PREFIX foaf: <https://xmlns.com/foaf/0.1/> PREFIX ex: <https://www.example.com/> \
       SELECT ?firstName WHERE { ex:JaneDoe foaf:knows ?person . ?person foaf:firstName ?firstName }" \
   -d "explain=dynamic"
```

A consulta agora retorna a saída em formato ASCII formatada (tipo de conteúdo HTTP `text/plain`), que é o tipo de saída padrão:

```
╔════╤════════╤════════╤═══════════════════╤═══════════════════════════════════════════════════════╤══════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name              │ Arguments                                             │ Mode     │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪═══════════════════════════════════════════════════════╪══════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0  │ 1      │ -      │ SolutionInjection │ solutions=[{}]                                        │ -        │ 0        │ 1         │ 0.00  │ 0         ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 1  │ 2      │ -      │ PipelineJoin      │ pattern=distinct(ex:JaneDoe, foaf:knows, ?person)     │ -        │ 1        │ 2         │ 2.00  │ 1         ║
║    │        │        │                   │ joinType=join                                         │          │          │           │       │           ║
║    │        │        │                   │ joinProjectionVars=[?person]                          │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 2  │ 3      │ -      │ PipelineJoin      │ pattern=distinct(?person, foaf:firstName, ?firstName) │ -        │ 2        │ 2         │ 1.00  │ 1         ║
║    │        │        │                   │ joinType=join                                         │          │          │           │       │           ║
║    │        │        │                   │ joinProjectionVars=[?person, ?firstName]              │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 3  │ 4      │ -      │ Projection        │ vars=[?firstName]                                     │ retain   │ 2        │ 2         │ 1.00  │ 0         ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 4  │ -      │ -      │ TermResolution    │ vars=[?firstName]                                     │ id2value │ 2        │ 2         │ 1.00  │ 1         ║
╚════╧════════╧════════╧═══════════════════╧═══════════════════════════════════════════════════════╧══════════╧══════════╧═══════════╧═══════╧═══════════╝
```

Para obter detalhes sobre as operações na coluna `Name` e seus argumentos, consulte [Operadores explain](sparql-explain-operators.md).

A tabela a seguir descreve a saída linha por linha:

1. A primeira etapa na consulta principal sempre usa o operador `SolutionInjection` para injetar uma solução. Depois, a solução é expandida para o resultado final por meio do processo de avaliação.

   Nesse caso, ele injeta a chamada solução universal `{ }`. Na presença de cláusulas `VALUES` ou de um `BIND`, esta etapa também pode injetar associações mais complexas com as quais começar.

   A coluna `Units Out` indica que o fluxo de saída dessa solução é feito fora do operador. A coluna `Out #1` especifica o operador no qual esse operador alimenta o resultado. Neste exemplo, todos os operadores são conectados ao operador seguinte na tabela.

1. A segunda etapa é um `PipelineJoin`. Ele recebe como entrada a única solução universal (totalmente irrestrita) produzida pelo operador anterior (`Units In := 1`). Ele a une com o padrão de tupla definido por seu argumento `pattern`. Isso corresponde a uma pesquisa simples para o padrão. Nesse caso, o padrão do triplo é definido como o seguinte:

   ```
   distinct( ex:JaneDoe, foaf:knows, ?person )
   ```

   O argumento `joinType := join` indica que esta é uma junção normal (outros tipos incluem junções `optional`, junções `existence check` e assim por diante).

   O argumento `distinct := true` diz que você extrai apenas correspondências distintas do banco de dados (sem duplicatas), e você associa as correspondências distintas à variável `joinProjectionVars := ?person`, desduplicada.

   O fato de que o valor da coluna `Units Out` é 2 indica que há duas soluções no fluxo de saída. Especificamente, essas são as associações da variável `?person`, que refletem as duas pessoas que os dados mostram que Jane Doe conhece:

   ```
    ?person
    -------------
    ex:JohnDoe
    ex:RichardRoe
   ```

1. As duas soluções da etapa 2 fluem como entrada (`Units In := 2`) no segundo `PipelineJoin`. Esse operador une as duas soluções anteriores com o seguinte padrão de triplo:

   ```
   distinct(?person, foaf:firstName, ?firstName)
   ```

   Sabe-se que a variável `?person` está associada a `ex:JohnDoe` ou a `ex:RichardRoe` pela solução de entrada do operador. Considerando isso, o `PipelineJoin` extrai os nomes, John e Richard. As duas soluções de saída (Units Out: = 2) são as seguintes:

   ```
    ?person       | ?firstName
    ---------------------------
    ex:JohnDoe    | John
    ex:RichardRoe | Richard
   ```

1. O próximo operador da projeção usa como entrada as duas soluções da etapa 3 (`Units In := 2`) e projeta para a variável `?firstName`. Isso elimina todas as outras associações da variável nos mapeamentos e passa as duas associações (`Units Out := 2`):

   ```
    ?firstName
    ----------
    John
    Richard
   ```

1. Para melhorar o desempenho, o Neptune opera sempre que possível em identificadores internos que ele atribui a termos URIs como literais de string, em vez de nas próprias strings. O operador final, `TermResolution`, executa um mapeamento desses identificadores internos de volta para as strings dos termos correspondentes.

   Na avaliação de consultas normais (sem explain), o resultado calculado pelo último operador é, então, serializado para o formato de serialização solicitado e transmitido para o cliente.

## Exemplo de saída do modo de detalhes
<a name="sparql-explain-example-details"></a>

Vamos supor que você execute a mesma consulta que a anterior no modo de *detalhes*, em vez de no modo *dinâmico*:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=PREFIX foaf: <https://xmlns.com/foaf/0.1/> PREFIX ex: <https://www.example.com/> \
       SELECT ?firstName WHERE { ex:JaneDoe foaf:knows ?person . ?person foaf:firstName ?firstName }" \
   -d "explain=details"
```

Como mostra este exemplo, a saída é a mesma com alguns detalhes adicionais, como a string de consulta na parte superior da saída e a contagem `patternEstimate` para o operador `PipelineJoin`:

```
Query:
PREFIX foaf: <https://xmlns.com/foaf/0.1/> PREFIX ex: <https://www.example.com/>
SELECT ?firstName WHERE { ex:JaneDoe foaf:knows ?person . ?person foaf:firstName ?firstName }

╔════╤════════╤════════╤═══════════════════╤═══════════════════════════════════════════════════════╤══════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name              │ Arguments                                             │ Mode     │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪═══════════════════════════════════════════════════════╪══════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0  │ 1      │ -      │ SolutionInjection │ solutions=[{}]                                        │ -        │ 0        │ 1         │ 0.00  │ 0         ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 1  │ 2      │ -      │ PipelineJoin      │ pattern=distinct(ex:JaneDoe, foaf:knows, ?person)     │ -        │ 1        │ 2         │ 2.00  │ 13        ║
║    │        │        │                   │ joinType=join                                         │          │          │           │       │           ║
║    │        │        │                   │ joinProjectionVars=[?person]                          │          │          │           │       │           ║
║    │        │        │                   │ patternEstimate=2                                     │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 2  │ 3      │ -      │ PipelineJoin      │ pattern=distinct(?person, foaf:firstName, ?firstName) │ -        │ 2        │ 2         │ 1.00  │ 3         ║
║    │        │        │                   │ joinType=join                                         │          │          │           │       │           ║
║    │        │        │                   │ joinProjectionVars=[?person, ?firstName]              │          │          │           │       │           ║
║    │        │        │                   │ patternEstimate=2                                     │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 3  │ 4      │ -      │ Projection        │ vars=[?firstName]                                     │ retain   │ 2        │ 2         │ 1.00  │ 1         ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 4  │ -      │ -      │ TermResolution    │ vars=[?firstName]                                     │ id2value │ 2        │ 2         │ 1.00  │ 7         ║
╚════╧════════╧════════╧═══════════════════╧═══════════════════════════════════════════════════════╧══════════╧══════════╧═══════════╧═══════╧═══════════╝
```

## Exemplo de saída de modo estático
<a name="sparql-explain-example-static"></a>

Vamos supor que você execute a mesma consulta que a anterior no modo *estático* (o padrão), em vez de no modo de *detalhes*:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=PREFIX foaf: <https://xmlns.com/foaf/0.1/> PREFIX ex: <https://www.example.com/> \
       SELECT ?firstName WHERE { ex:JaneDoe foaf:knows ?person . ?person foaf:firstName ?firstName }" \
   -d "explain=static"
```

Como mostra o exemplo, a saída é a mesma, com a exceção de que ela omite as últimas três colunas:

```
╔════╤════════╤════════╤═══════════════════╤═══════════════════════════════════════════════════════╤══════════╗
║ ID │ Out #1 │ Out #2 │ Name              │ Arguments                                             │ Mode     ║
╠════╪════════╪════════╪═══════════════════╪═══════════════════════════════════════════════════════╪══════════╣
║ 0  │ 1      │ -      │ SolutionInjection │ solutions=[{}]                                        │ -        ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────╢
║ 1  │ 2      │ -      │ PipelineJoin      │ pattern=distinct(ex:JaneDoe, foaf:knows, ?person)     │ -        ║
║    │        │        │                   │ joinType=join                                         │          ║
║    │        │        │                   │ joinProjectionVars=[?person]                          │          ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────╢
║ 2  │ 3      │ -      │ PipelineJoin      │ pattern=distinct(?person, foaf:firstName, ?firstName) │ -        ║
║    │        │        │                   │ joinType=join                                         │          ║
║    │        │        │                   │ joinProjectionVars=[?person, ?firstName]              │          ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────╢
║ 3  │ 4      │ -      │ Projection        │ vars=[?firstName]                                     │ retain   ║
╟────┼────────┼────────┼───────────────────┼───────────────────────────────────────────────────────┼──────────╢
║ 4  │ -      │ -      │ TermResolution    │ vars=[?firstName]                                     │ id2value ║
╚════╧════════╧════════╧═══════════════════╧═══════════════════════════════════════════════════════╧══════════╝
```

## Diferentes formas de codificar parâmetros
<a name="sparql-explain-example-parameters"></a>

As consultas de exemplo a seguir ilustram duas formas diferentes de codificar parâmetros ao invocar o `explain` do SPARQL.

**Usar a codificação de URL**: este exemplo usa a codificação de URL de parâmetros e especifica a saída *dinâmica*:

```
curl -XGET "http(s)://your_server:your_port/sparql?query=SELECT%20*%20WHERE%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D%20LIMIT%20%31&explain=dynamic"
```

**Especificar os parâmetros diretamente**: esta consulta é igual à anterior, com a exceção de que ela transmite os parâmetros diretamente por meio de POST:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=SELECT * WHERE { ?s ?p ?o } LIMIT 1" \
   -d "explain=dynamic"
```

## Outros tipos de saída além de texto/sem formatação
<a name="sparql-explain-output-options"></a>

Os exemplos anteriores usam o tipo de saída de `text/plain` padrão. O Neptune também pode formatar a saída de `explain` SPARQL em dois outros formatos do tipo MIME, ou seja, `text/csv` e `text/html`. Você as invoca configurando o cabeçalho `Accept` de HTTP, o que pode ser feito usando o sinalizador `-H` no `curl`, da seguinte forma:

```
  -H "Accept: output type"
```

Veja alguns exemplos:

**Saída `text/csv`**  
Essa consulta chama a saída CSV de tipo MIME especificando `-H "Accept: text/csv"`:

```
 curl http(s)://your_server:your_port/sparql \
   -d "query=SELECT * WHERE { ?s ?p ?o } LIMIT 1" \
   -d "explain=dynamic" \
   -H "Accept: text/csv"
```

O formato CSV, que é útil para importação em uma planilha ou banco de dados, separa os campos em cada linha do `explain` com ponto e vírgulas ( `;` ), da seguinte forma:

```
ID;Out #1;Out #2;Name;Arguments;Mode;Units In;Units Out;Ratio;Time (ms)
0;1;-;SolutionInjection;solutions=[{}];-;0;1;0.00;0
1;2;-;PipelineJoin;pattern=distinct(?s, ?p, ?o),joinType=join,joinProjectionVars=[?s, ?p, ?o];-;1;6;6.00;1
2;3;-;Projection;vars=[?s, ?p, ?o];retain;6;6;1.00;2
3;-;-;Slice;limit=1;-;1;1;1.00;1
```

 

**Saída `text/html`**  
Se você especificar `-H "Accept: text/html"`, o `explain` gerará uma tabela HTML:

```
<!DOCTYPE html>
<html>
  <body>
    <table border="1px">
      <thead>
        <tr>
          <th>ID</th>
          <th>Out #1</th>
          <th>Out #2</th>
          <th>Name</th>
          <th>Arguments</th>
          <th>Mode</th>
          <th>Units In</th>
          <th>Units Out</th>
          <th>Ratio</th>
          <th>Time (ms)</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>0</td>
          <td>1</td>
          <td>-</td>
          <td>SolutionInjection</td>
          <td>solutions=[{}]</td>
          <td>-</td>
          <td>0</td>
          <td>1</td>
          <td>0.00</td>
          <td>0</td>
        </tr>

        <tr>
          <td>1</td>
          <td>2</td>
          <td>-</td>
          <td>PipelineJoin</td>
          <td>pattern=distinct(?s, ?p, ?o)<br>
              joinType=join<br>
              joinProjectionVars=[?s, ?p, ?o]</td>
          <td>-</td>
          <td>1</td>
          <td>6</td>
          <td>6.00</td>
          <td>1</td>
        </tr>

        <tr>
          <td>2</td>
          <td>3</td>
          <td>-</td>
          <td>Projection</td>
          <td>vars=[?s, ?p, ?o]</td>
          <td>retain</td>
          <td>6</td>
          <td>6</td>
          <td>1.00</td>
          <td>2</td>
        </tr>

        <tr>
          <td>3</td>
          <td>-</td>
          <td>-</td>
          <td>Slice</td>
          <td>limit=1</td>
          <td>-</td>
          <td>1</td>
          <td>1</td>
          <td>1.00</td>
          <td>1</td>
        </tr>
      </tbody>
    </table>
  </body>
</html>
```

O HTML renderizará em um navegador algo como o seguinte:

![\[Exemplo de saída HTML do explain do SPARQL.\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/images/sparql-explain-dynamic-html-output.png)


## Exemplo de saída de `explain` SPARQL quando o DFE está habilitado
<a name="sparql-explain-output-dfe"></a>

Veja um exemplo de saída de `explain` SPARQL quando o mecanismo de consulta alternativo do DFE no Neptune está habilitado:

```
╔════╤════════╤════════╤═══════════════════╤═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name              │ Arguments                                                                                                                                                                                                               │ Mode     │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0  │ 1      │ -      │ SolutionInjection │ solutions=[{}]                                                                                                                                                                                                          │ -        │ 0        │ 1         │ 0.00  │ 0         ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 1  │ 2      │ -      │ HashIndexBuild    │ solutionSet=solutionSet1                                                                                                                                                                                                │ -        │ 1        │ 1         │ 1.00  │ 22        ║
║    │        │        │                   │ joinVars=[]                                                                                                                                                                                                             │          │          │           │       │           ║
║    │        │        │                   │ sourceType=pipeline                                                                                                                                                                                                     │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 2  │ 3      │ -      │ DFENode           │ DFE Stats=                                                                                                                                                                                                                    │ -        │ 101      │ 100       │ 0.99  │ 32        ║
║    │        │        │                   │ ====> DFE execution time (measured by DFEQueryEngine)                                                                                                                                                                   │          │          │           │       │           ║
║    │        │        │                   │ accepted [micros]=127                                                                                                                                                                                                   │          │          │           │       │           ║
║    │        │        │                   │ ready [micros]=2                                                                                                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │ running [micros]=5627                                                                                                                                                                                                   │          │          │           │       │           ║
║    │        │        │                   │ finished [micros]=0                                                                                                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ ===> DFE execution time (measured in DFENode)                                                                                                                                                                           │          │          │           │       │           ║
║    │        │        │                   │ -> setupTime [ms]=1                                                                                                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │ -> executionTime [ms]=14                                                                                                                                                                                                │          │          │           │       │           ║
║    │        │        │                   │ -> resultReadTime [ms]=0                                                                                                                                                                                                │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ ===> Static analysis statistics                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ --> 35907 micros spent in parser.                                                                                                                                                                                       │          │          │           │       │           ║
║    │        │        │                   │ --> 7643 micros spent in range count estimation                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ --> 2895 micros spent in value resolution                                                                                                                                                                               │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ --> 39974925 micros spent in optimizer loop                                                                                                                                                                             │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ DFEJoinGroupNode[ children={                                                                                                                                                                                            │          │          │           │       │           ║
║    │        │        │                   │   DFEPatternNode[(?1, TERM[117442062], ?2, ?3) . project DISTINCT[?1, ?2] {rangeCountEstimate=100},                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │     OperatorInfoWithAlternative[                                                                                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │       rec=OperatorInfo[                                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         type=INCREMENTAL_PIPELINE_JOIN,                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         costEstimates=OperatorCostEstimates[                                                                                                                                                                            │          │          │           │       │           ║
║    │        │        │                   │           costEstimate=OperatorCostEstimate[in=1.0000,out=100.0000,io=0.0002,comp=0.0000,mem=0],                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │           worstCaseCostEstimate=OperatorCostEstimate[in=1.0000,out=100.0000,io=0.0002,comp=0.0000,mem=0]]],                                                                                                             │          │          │           │       │           ║
║    │        │        │                   │       alt=OperatorInfo[                                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         type=INCREMENTAL_HASH_JOIN,                                                                                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │         costEstimates=OperatorCostEstimates[                                                                                                                                                                            │          │          │           │       │           ║
║    │        │        │                   │           costEstimate=OperatorCostEstimate[in=1.0000,out=100.0000,io=0.0003,comp=0.0000,mem=3212],                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │           worstCaseCostEstimate=OperatorCostEstimate[in=1.0000,out=100.0000,io=0.0003,comp=0.0000,mem=3212]]]]],                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │   DFEPatternNode[(?1, TERM[150997262], ?4, ?5) . project DISTINCT[?1, ?4] {rangeCountEstimate=100},                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │     OperatorInfoWithAlternative[                                                                                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │       rec=OperatorInfo[                                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         type=INCREMENTAL_HASH_JOIN,                                                                                                                                                                                     │          │          │           │       │           ║
║    │        │        │                   │         costEstimates=OperatorCostEstimates[                                                                                                                                                                            │          │          │           │       │           ║
║    │        │        │                   │           costEstimate=OperatorCostEstimate[in=100.0000,out=100.0000,io=0.0003,comp=0.0000,mem=6400],                                                                                                                   │          │          │           │       │           ║
║    │        │        │                   │           worstCaseCostEstimate=OperatorCostEstimate[in=100.0000,out=100.0000,io=0.0003,comp=0.0000,mem=6400]]],                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │       alt=OperatorInfo[                                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         type=INCREMENTAL_PIPELINE_JOIN,                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │         costEstimates=OperatorCostEstimates[                                                                                                                                                                            │          │          │           │       │           ║
║    │        │        │                   │           costEstimate=OperatorCostEstimate[in=100.0000,out=100.0000,io=0.0010,comp=0.0000,mem=0],                                                                                                                      │          │          │           │       │           ║
║    │        │        │                   │           worstCaseCostEstimate=OperatorCostEstimate[in=100.0000,out=100.0000,io=0.0010,comp=0.0000,mem=0]]]]]                                                                                                          │          │          │           │       │           ║
║    │        │        │                   │ },                                                                                                                                                                                                                      │          │          │           │       │           ║
║    │        │        │                   │ ]                                                                                                                                                                                                                       │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ ===> DFE configuration:                                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │ solutionChunkSize=5000                                                                                                                                                                                                  │          │          │           │       │           ║
║    │        │        │                   │ ouputQueueSize=20                                                                                                                                                                                                       │          │          │           │       │           ║
║    │        │        │                   │ numComputeCores=3                                                                                                                                                                                                       │          │          │           │       │           ║
║    │        │        │                   │ maxParallelIO=10                                                                                                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │ numInitialPermits=12                                                                                                                                                                                                    │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ ====> DFE configuration (reported back)                                                                                                                                                                                 │          │          │           │       │           ║
║    │        │        │                   │ numComputeCores=3                                                                                                                                                                                                       │          │          │           │       │           ║
║    │        │        │                   │ maxParallelIO=2                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ numInitialPermits=12                                                                                                                                                                                                    │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ ===> Statistics & operator histogram                                                                                                                                                                                    │          │          │           │       │           ║
║    │        │        │                   │ ==> Statistics                                                                                                                                                                                                          │          │          │           │       │           ║
║    │        │        │                   │ -> 3741 / 3668 micros total elapsed (incl. wait / excl. wait)                                                                                                                                                           │          │          │           │       │           ║
║    │        │        │                   │ -> 3741 / 3 millis total elapse (incl. wait / excl. wait)                                                                                                                                                               │          │          │           │       │           ║
║    │        │        │                   │ -> 3741 / 0 secs total elapsed (incl. wait / excl. wait)                                                                                                                                                                │          │          │           │       │           ║
║    │        │        │                   │ ==> Operator histogram                                                                                                                                                                                                  │          │          │           │       │           ║
║    │        │        │                   │ -> 47.66% of total time (excl. wait): pipelineScan (2 instances)                                                                                                                                                        │          │          │           │       │           ║
║    │        │        │                   │ -> 10.99% of total time (excl. wait): merge (1 instances)                                                                                                                                                               │          │          │           │       │           ║
║    │        │        │                   │ -> 41.17% of total time (excl. wait): symmetricHashJoin (1 instances)                                                                                                                                                   │          │          │           │       │           ║
║    │        │        │                   │ -> 0.19% of total time (excl. wait): drain (1 instances)                                                                                                                                                                │          │          │           │       │           ║
║    │        │        │                   │                                                                                                                                                                                                                         │          │          │           │       │           ║
║    │        │        │                   │ nodeId | out0   | out1 | opName            | args                                             | rowsIn | rowsOut | chunksIn | chunksOut | elapsed* | outWait | outBlocked | ratio    | rate* [M/s] | rate [M/s] | %     │          │          │           │       │           ║
║    │        │        │                   │ ------ | ------ | ---- | ----------------- | ------------------------------------------------ | ------ | ------- | -------- | --------- | -------- | ------- | ---------- | -------- | ----------- | ---------- | ----- │          │          │           │       │           ║
║    │        │        │                   │ node_0 | node_2 | -    | pipelineScan      | (?1, TERM[117442062], ?2, ?3) DISTINCT [?1, ?2]  | 0      | 100     | 0        | 1         | 874      | 0       | 0          | Infinity | 0.1144      | 0.1144     | 23.83 │          │          │           │       │           ║
║    │        │        │                   │ node_1 | node_2 | -    | pipelineScan      | (?1, TERM[150997262], ?4, ?5) DISTINCT [?1, ?4]  | 0      | 100     | 0        | 1         | 874      | 0       | 0          | Infinity | 0.1144      | 0.1144     | 23.83 │          │          │           │       │           ║
║    │        │        │                   │ node_2 | node_4 | -    | symmetricHashJoin |                                                  | 200    | 100     | 2        | 2         | 1510     | 73      | 0          | 0.50     | 0.0662      | 0.0632     | 41.17 │          │          │           │       │           ║
║    │        │        │                   │ node_3 | -      | -    | drain             |                                                  | 100    | 0       | 1        | 0         | 7        | 0       | 0          | 0.00     | 0.0000      | 0.0000     | 0.19  │          │          │           │       │           ║
║    │        │        │                   │ node_4 | node_3 | -    | merge             |                                                  | 100    | 100     | 2        | 1         | 403      | 0       | 0          | 1.00     | 0.2481      | 0.2481     | 10.99 │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 3  │ 4      │ -      │ HashIndexJoin     │ solutionSet=solutionSet1                                                                                                                                                                                                │ -        │ 100      │ 100       │ 1.00  │ 4         ║
║    │        │        │                   │ joinType=join                                                                                                                                                                                                           │          │          │           │       │           ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 4  │ 5      │ -      │ Distinct          │ vars=[?s, ?o, ?o1]                                                                                                                                                                                                      │ -        │ 100      │ 100       │ 1.00  │ 9         ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 5  │ 6      │ -      │ Projection        │ vars=[?s, ?o, ?o1]                                                                                                                                                                                                      │ retain   │ 100      │ 100       │ 1.00  │ 2         ║
╟────┼────────┼────────┼───────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 6  │ -      │ -      │ TermResolution    │ vars=[?s, ?o, ?o1]                                                                                                                                                                                                      │ id2value │ 100      │ 100       │ 1.00  │ 11        ║
╚════╧════════╧════════╧═══════════════════╧═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╧══════════╧══════════╧═══════════╧═══════╧═══════════╝
```

# Operadores SPARQL `explain` no Neptune
<a name="sparql-explain-operators"></a>

As seções a seguir descrevem os operadores e os parâmetros para o atributo `explain` do SPARQL que está disponível no Amazon Neptune.

**Importante**  
O recurso `explain` do SPARQL ainda está sendo refinado. Os operadores e os parâmetros documentados aqui podem ser alterados em versões futuras.

**Topics**
+ [Operador `Aggregation`](#sparql-explain-operator-aggregation)
+ [Operador `ConditionalRouting`](#sparql-explain-operator-conditional-routing)
+ [Operador `Copy`](#sparql-explain-operator-copy)
+ [Operador `DFENode`](#sparql-explain-operator-dfenode)
+ [Operador `Distinct`](#sparql-explain-operator-distinct)
+ [Operador `Federation`](#sparql-explain-operator-federation)
+ [Operador `Filter`](#sparql-explain-operator-filter)
+ [Operador `HashIndexBuild`](#sparql-explain-operator-hash-index-build)
+ [Operador `HashIndexJoin`](#sparql-explain-operator-hash-index-join)
+ [Operador `MergeJoin`](#sparql-explain-operator-merge-join)
+ [Operador `NamedSubquery`](#sparql-explain-operator-named-subquery)
+ [Operador `PipelineJoin`](#sparql-explain-operator-pipeline-join)
+ [Operador `PipelineCountJoin`](#sparql-explain-operator-pipeline-count-join)
+ [Operador `PipelinedHashIndexJoin`](#sparql-explain-operator-pipeline-hash-index-join)
+ [Operador `Projection`](#sparql-explain-operator-projection)
+ [Operador `PropertyPath`](#sparql-explain-operator-property-path)
+ [Operador `TermResolution`](#sparql-explain-operator-term-resolution)
+ [Operador `Slice`](#sparql-explain-operator-slice)
+ [Operador `SolutionInjection`](#sparql-explain-operator-solution-injection)
+ [Operador `Sort`](#sparql-explain-operator-sort)
+ [Operador `VariableAlignment`](#sparql-explain-operator-variable-alignment)

## Operador `Aggregation`
<a name="sparql-explain-operator-aggregation"></a>

Executa uma ou mais agregações, implementando a semântica dos operadores de agregação do SPARQL, como `count`, `max`, `min`, `sum` e assim por diante.

`Aggregation` é fornecido com agrupamento opcional usando cláusulas `groupBy` e restrições `having` opcionais.

**Argumentos**
+ `groupBy`: (*opcional*) fornece uma cláusula `groupBy` que especifica a sequência de expressões de acordo com a qual as soluções de entrada são agrupadas.
+ `aggregates`: (*obrigatório*) especifica uma lista ordenada de expressões de agregação.
+ `having`: (*opcional*) adiciona restrições para filtragem em grupos, como implícito pela cláusula `having` na consulta do SPARQL.

## Operador `ConditionalRouting`
<a name="sparql-explain-operator-conditional-routing"></a>

Roteia soluções de entrada com base em uma determinada condição. As soluções que atendem à condição são roteadas para o ID do operador referenciado por `Out #1`, enquanto as soluções que não atendem são roteadas para o operador referenciado por `Out #2`.

**Argumentos**
+ `condition`: (*obrigatório*) a condição de roteamento.

## Operador `Copy`
<a name="sparql-explain-operator-copy"></a>

Delega o fluxo da solução conforme especificado pelo modo especificado.

**Modos**
+ `forward`: encaminha as soluções para o operador posterior identificado por `Out #1`. 
+ `duplicate`: duplica as soluções e as encaminha para cada um dos dois operadores identificados por `Out #1` e `Out #2`.

O `Copy` não tem argumentos.

## Operador `DFENode`
<a name="sparql-explain-operator-dfenode"></a>

Esse operador é uma abstração do plano executado pelo mecanismo de consulta alternativa do DFE. O plano detalhado do DFE é descrito nos argumentos para esse operador. No momento, o argumento está sobrecarregado para conter as estatísticas detalhadas de runtime do plano do DFE. Ele contém o tempo gasto nas várias etapas da execução da consulta pelo DFE.

A árvore de sintaxe abstrata (AST) de lógica otimizada para o plano de consulta do DFE é impressa com informações sobre os tipos de operadores que foram considerados durante o planejamento e os melhores e piores custos associados à execução dos operadores. O AST consiste nos seguintes tipos de nós no momento:
+ `DFEJoinGroupNode`: representa uma junção de um ou mais `DFEPatternNodes`.
+ `DFEPatternNode`: encapsula um padrão subjacente usando as tuplas correspondentes que se projetam para fora do banco de dados subjacente.

A subseção, `Statistics & Operator histogram`, contém detalhes sobre o tempo de execução do plano `DataflowOp` e o detalhamento do tempo de CPU usado por cada operador. Abaixo disso, há uma tabela que imprime estatísticas detalhadas de runtime do plano executado pelo DFE.

**nota**  
O DFE é um atributo experimental lançado no modo de laboratório, portanto, o formato exato da saída de `explain` pode mudar.

## Operador `Distinct`
<a name="sparql-explain-operator-distinct"></a>

Calcula a projeção distinta em um subconjunto das variáveis, eliminando duplicatas. Como resultado, o número de soluções do fluxo de entrada é maior ou igual ao número de soluções do fluxo de saída.

**Argumentos**
+ `vars`: (*obrigatório*) as variáveis às quais aplicar a projeção `Distinct`.

## Operador `Federation`
<a name="sparql-explain-operator-federation"></a>

Transmite uma consulta especificada para um endpoint SPARQL remoto especificado.

**Argumentos**
+ `endpoint`: (*obrigatório*) o URL do endpoint na declaração `SERVICE` do SPARQL. Pode ser uma string constante ou, se o endpoint da consulta for determinado com base em uma variável dentro da mesma consulta, pode ser o nome da variável.
+ `query`: (*obrigatório*) a string de consulta reconstruída a ser enviada ao endpoint remoto. O mecanismo adiciona prefixos padrão a essa consulta, mesmo quando o cliente não especifica nenhum.
+ `silent`: (*obrigatório*) um booliano que indica se a palavra-chave `SILENT` apareceu após a palavra-chave. `SILENT` ordena ao mecanismo para não causar falha na consulta inteira, mesmo que a parte remota de `SERVICE` falhe.

## Operador `Filter`
<a name="sparql-explain-operator-filter"></a>

Filtra as soluções de entrada. Somente as soluções que atendem à condição do filtro são encaminhadas para o operador upstream, e todas as outras são descartadas.

**Argumentos**
+ `condition`: (*obrigatório*) a condição de filtro.

## Operador `HashIndexBuild`
<a name="sparql-explain-operator-hash-index-build"></a>

Usa uma lista de associações e as transfere para um índice de hash cujo nome é definido pelo argumento `solutionSet`. Normalmente, os operadores subsequentes executam junções nesse conjunto de soluções, referindo-se a ele por esse nome.

**Argumentos**
+ `solutionSet`: (*obrigatório*) o nome do conjunto de soluções do índice de hash.
+ `sourceType`: (*obrigatório*) o tipo da origem a partir da qual as associações a serem armazenadas no índice de hash são obtidas:
  + `pipeline`: transfere as soluções de entrada do operador posterior para o pipeline de operadores no índice de hash.
  + `binding set`: transfere o conjunto de associações fixas especificado pelo argumento `sourceBindingSet` ao índice de hash.
+ `sourceBindingSet`: (*opcional*) se o valor do argumento `sourceType` for `binding set`, esse argumento especificará o conjunto de associações estáticas a serem transferidas ao índice de hash.

## Operador `HashIndexJoin`
<a name="sparql-explain-operator-hash-index-join"></a>

Une as soluções de entrada no conjunto de soluções do índice de hash identificado pelo argumento `solutionSet`.

**Argumentos**
+ `solutionSet`: (*obrigatório*) o nome do conjunto de soluções no qual fazer a junção. Esse deve ser um índice de hash que foi criado em uma etapa anterior usando o operador `HashIndexBuild`.
+ `joinType`: (*obrigatório*) o tipo de junção a ser executada:
  + `join`: uma junção normal, que exige uma correspondência exata entre todas as variáveis compartilhadas.
  + `optional`: uma junção `optional` que usa a semântica do operador `OPTIONAL` do SPARQL.
  + `minus`: uma operação `minus` mantém um mapeamento para o qual não existe nenhum parceiro de junção usando o operador `MINUS` do SPARQL.
  + `existence check`: confere se há um parceiro de junção e associa a variável `existenceCheckResultVar` ao resultado dessa verificação.
+ `constraints`: (*opcional*) restrições adicionais de junção que são consideradas durante a junção. Junções que não atendem a essas restrições são descartadas.
+ `existenceCheckResultVar`: (*opcional*) Usado apenas para junções em que `joinType` é igual a `existence check` (veja o argumento `joinType` anterior).

## Operador `MergeJoin`
<a name="sparql-explain-operator-merge-join"></a>

Uma junção de mesclagem em vários conjuntos de soluções, conforme identificado pelo argumento `solutionSets`.

**Argumentos**
+ `solutionSets`: (*obrigatório*) os conjuntos de soluções a serem unidos.

## Operador `NamedSubquery`
<a name="sparql-explain-operator-named-subquery"></a>

Aciona a avaliação da subconsulta identificada pelo argumento `subQuery` e transfere o resultado para o conjunto de soluções especificado pelo argumento `solutionSet`. As soluções de entrada para o operador são encaminhadas para a subconsulta e então para o próximo operador.

**Argumentos**
+ `subQuery`: (*obrigatório*) o nome da subconsulta a ser avaliada. A subconsulta é renderizada explicitamente na saída.
+ `solutionSet`: (*obrigatório*) o nome do conjunto de soluções no qual armazenar o resultado da subconsulta.

## Operador `PipelineJoin`
<a name="sparql-explain-operator-pipeline-join"></a>

Recebe como entrada a saída do operador anterior e junta-a no padrão de tupla definido pelo argumento `pattern`.

**Argumentos**
+ `pattern`— (*Obrigatório*) O padrão, que assume a forma de uma tupla e subject-predicate-object, opcionalmente, de gráfico que está por trás da junção. Se `distinct` for especificado para o padrão, a junção extrairá apenas as soluções distintas das variáveis de projeção especificadas pelo argumento `projectionVars`, em vez de todas as soluções correspondentes.
+ `inlineFilters`: (*opcional*) um conjunto de filtros a serem aplicados às variáveis no padrão. O padrão é avaliado em conjunto com esses filtros.
+ `joinType`: (*obrigatório*) o tipo de junção a ser executada:
  + `join`: uma junção normal, que exige uma correspondência exata entre todas as variáveis compartilhadas.
  + `optional`: uma junção `optional` que usa a semântica do operador `OPTIONAL` do SPARQL.
  + `minus`: uma operação `minus` mantém um mapeamento para o qual não existe nenhum parceiro de junção usando o operador `MINUS` do SPARQL.
  + `existence check`: confere se há um parceiro de junção e associa a variável `existenceCheckResultVar` ao resultado dessa verificação.
+ `constraints`: (*opcional*) restrições adicionais de junção que são consideradas durante a junção. Junções que não atendem a essas restrições são descartadas.
+ `projectionVars`: (*opcional*) as variáveis da projeção. Usado em combinação com `distinct := true` para impor a extração de projeções distintas em um conjunto de variáveis especificado.
+ `cutoffLimit`: (*opcional*) um limite de corte para o número de parceiros de junção extraídos. Embora não exista nenhum limite por padrão, você pode definir isso como 1 ao executar junções para implementar cláusulas `FILTER (NOT) EXISTS`, em que é suficiente provar ou refutar que existe um parceiro de junção.

## Operador `PipelineCountJoin`
<a name="sparql-explain-operator-pipeline-count-join"></a>

Variante do `PipelineJoin`. Em vez de juntar, ele simplesmente conta os parceiros da junção correspondente e associa a contagem à variável especificada pelo argumento `countVar`.

**Argumentos**
+ `countVar`: (*obrigatório*) a variável à qual o resultado da contagem, ou seja, o número de parceiros da junção, deve ser associado.
+ `pattern`— (*Obrigatório*) O padrão, que assume a forma de uma tupla e subject-predicate-object, opcionalmente, de gráfico que está por trás da junção. Se `distinct` for especificado para o padrão, a junção extrairá apenas as soluções distintas das variáveis de projeção especificadas pelo argumento `projectionVars`, em vez de todas as soluções correspondentes.
+ `inlineFilters`: (*opcional*) um conjunto de filtros a serem aplicados às variáveis no padrão. O padrão é avaliado em conjunto com esses filtros.
+ `joinType`: (*obrigatório*) o tipo de junção a ser executada:
  + `join`: uma junção normal, que exige uma correspondência exata entre todas as variáveis compartilhadas.
  + `optional`: uma junção `optional` que usa a semântica do operador `OPTIONAL` do SPARQL.
  + `minus`: uma operação `minus` mantém um mapeamento para o qual não existe nenhum parceiro de junção usando o operador `MINUS` do SPARQL.
  + `existence check`: confere se há um parceiro de junção e associa a variável `existenceCheckResultVar` ao resultado dessa verificação.
+ `constraints`: (*opcional*) restrições adicionais de junção que são consideradas durante a junção. Junções que não atendem a essas restrições são descartadas.
+ `projectionVars`: (*opcional*) as variáveis da projeção. Usado em combinação com `distinct := true` para impor a extração de projeções distintas em um conjunto de variáveis especificado.
+ `cutoffLimit`: (*opcional*) um limite de corte para o número de parceiros de junção extraídos. Embora não exista nenhum limite por padrão, você pode definir isso como 1 ao executar junções para implementar cláusulas `FILTER (NOT) EXISTS`, em que é suficiente provar ou refutar que existe um parceiro de junção.

## Operador `PipelinedHashIndexJoin`
<a name="sparql-explain-operator-pipeline-hash-index-join"></a>

Este é um índice de hash de all-in-one construção e um operador de junção. Ele pega uma lista de associações, as agrupa em um índice de hash e, depois, une as soluções de entrada com o índice de hash.

**Argumentos**
+ `sourceType`: (*obrigatório*) o tipo da origem a partir da qual as associações a serem armazenadas no índice de hash são obtidas. Um de:
  + `pipeline`: faz com que o `PipelinedHashIndexJoin` transfira as soluções de entrada do operador posterior no pipeline de operadores para o índice de hash.
  + `binding set`: faz com que `PipelinedHashIndexJoin` transfira o conjunto de associações fixas especificado pelo argumento `sourceBindingSet` para o índice de hash.
+ `sourceSubQuery `: (*opcional*) se o valor do argumento `sourceType` for `pipeline`, esse argumento especificará a subconsulta avaliada e agrupada no índice de hash.
+ `sourceBindingSet `: (*opcional*) se o valor do argumento `sourceType` for `binding set`, esse argumento especificará o conjunto de associações estáticas a serem transferidas para o índice de hash.
+ `joinType`: (*obrigatório*) o tipo de junção a ser executada:
  + `join`: uma junção normal, que exige uma correspondência exata entre todas as variáveis compartilhadas.
  + `optional`: uma junção `optional` que usa a semântica do operador `OPTIONAL` do SPARQL.
  + `minus`: uma operação `minus` mantém um mapeamento para o qual não existe nenhum parceiro de junção usando o operador `MINUS` do SPARQL.
  + `existence check`: confere se há um parceiro de junção e associa a variável `existenceCheckResultVar` ao resultado dessa verificação.
+ `existenceCheckResultVar`: (*opcional*) usado apenas para junções em que `joinType` é igual a `existence check` (veja o argumento joinType acima).

## Operador `Projection`
<a name="sparql-explain-operator-projection"></a>

Projeta sobre um subconjunto de variáveis. O número de soluções do fluxo de entrada é igual ao número de soluções do fluxo de saída, mas a forma da solução é diferente, dependendo da configuração do modo.

**Modos**
+ `retain`: reter nas soluções apenas as variáveis que são especificadas pelo argumento `vars`.
+ `drop`: descartar todas as variáveis especificadas pelo argumento `vars`.

**Argumentos**
+ `vars`: (*obrigatório*) as variáveis a serem retidas ou descartadas, dependendo da configuração do modo.

## Operador `PropertyPath`
<a name="sparql-explain-operator-property-path"></a>

Habilita caminhos de propriedades recursivos, como `+` ou `*`. O Neptune implementa uma abordagem de iteração de ponto fixo com base em um modelo especificado pelo argumento `iterationTemplate`. As variáveis conhecidas do lado esquerdo ou direito são associadas no modelo para cada iteração de ponto fixo, até que nenhuma nova solução possa ser encontrada.

**Argumentos**
+ `iterationTemplate`: (*obrigatório*) o nome do modelo de subconsulta usado para implementar a iteração de ponto fixo.
+ `leftTerm`: (*obrigatório*) o termo (variável ou constante) no lado esquerdo do caminho da propriedade.
+ `rightTerm`: (*obrigatório*) o termo (variável ou constante) no lado direito do caminho da propriedade.
+ `lowerBound`: (*obrigatório*) O limite inferior para iteração de ponto fixo (`0` para consultas `*` ou `1` para consultas `+`).

## Operador `TermResolution`
<a name="sparql-explain-operator-term-resolution"></a>

Converte valores de identificadores de strings internas de volta para suas strings externas correspondentes, ou converte strings externas em valores de identificadores de strings internas, dependendo do modo.

**Modos**
+ `value2id`— Mapeia termos como literais e URIs para valores de ID internos correspondentes (codificação para valores internos).
+ `id2value`— Mapeia valores de ID internos para os termos correspondentes, como literais e URIs (decodificação de valores internos).

**Argumentos**
+ `vars`— (*Obrigatório*) Especifica as variáveis cujas cadeias de caracteres ou seqüências de caracteres internas IDs devem ser mapeadas.

## Operador `Slice`
<a name="sparql-explain-operator-slice"></a>

Implementa um slice sobre o fluxo da solução de entrada, usando a semântica das cláusulas `LIMIT` e `OFFSET` do SPARQL.

**Argumentos**
+ `limit`: (*opcional*) um limite das soluções a serem encaminhadas.
+ `offset`: (*opcional*) o deslocamento em que as soluções são avaliadas para encaminhamento.

## Operador `SolutionInjection`
<a name="sparql-explain-operator-solution-injection"></a>

Não recebe nenhuma entrada. Injeta estaticamente soluções no plano de consulta e registra-as no argumento `solutions`.

Os planos de consulta sempre começam com essa injeção estática. Se as soluções estáticas a serem injetadas puderem ser derivadas da própria consulta combinando várias origens de associações estáticas (por exemplo, de cláusulas `VALUES` ou `BIND`), o operador `SolutionInjection` injetará essas soluções estáticas derivadas. No caso mais simples, essas refletem associações que são implícitas por uma cláusula `VALUES` externa.

Se nenhuma solução estática puder ser derivada da consulta, `SolutionInjection` injetará a solução vazia, chamada de solução universal, que é expandida e multiplicada durante todo o processo de avaliação da consulta.

**Argumentos**
+ `solutions`: (*obrigatório*) a sequência de soluções injetadas pelo operador.

## Operador `Sort`
<a name="sparql-explain-operator-sort"></a>

Classifica o conjunto de soluções usando as condições de classificação especificadas.

**Argumentos**
+ `sortOrder`: (*obrigatório*) lista ordenada de variáveis, cada uma contendo um identificador `ASC` (crescente) ou `DESC` (decrescente), usado sequencialmente para classificar o conjunto de soluções.

## Operador `VariableAlignment`
<a name="sparql-explain-operator-variable-alignment"></a>

Inspeciona uma por uma das soluções, executando alinhamento em cada uma por meio de duas variáveis: uma `sourceVar` especificada e uma `targetVar` especificada.

Se `sourceVar` e `targetVar` em uma solução tiverem o mesmo valor, as variáveis serão consideradas alinhadas, e a solução será encaminhada, com a `sourceVar` redundante descartada.

Se as variáveis estiverem associadas a valores diferentes, a solução será filtrada por completo.

**Argumentos**
+ `sourceVar`: (*obrigatório*) a variável de origem, a ser comparada com a variável de destino. Se o alinhamento for bem-sucedido em uma solução, indicando que as duas variáveis têm o mesmo valor, a variável de origem será descartada.
+ `targetVar`: (*obrigatório*) a variável de destino, com a qual a variável de origem é comparada. É retida mesmo quando o alinhamento é bem-sucedido.

# Limitações do SPARQL `explain` no Neptune
<a name="sparql-explain-limitations"></a>

A versão do atributo `explain` do SPARQL no Neptune tem as limitações a seguir.

**No momento, o Neptune é compatível com explain apenas em consultas SELECT do SPARQL**  
Para obter informações sobre o processo de avaliação para outras formas de consulta, como consultas `ASK`, `CONSTRUCT`, `DESCRIBE` e `SPARQL UPDATE`, você pode transformar essas consultas em uma consulta SELECT. Depois, use `explain` para inspecionar a consulta SELECT correspondente.

Por exemplo, para obter informações do `explain` sobre uma consulta `ASK WHERE {...}`, execute a consulta `SELECT WHERE {...} LIMIT 1` correspondente com o `explain`.

Da mesma forma, em uma consulta `CONSTRUCT {...} WHERE {...}`, descarte a parte `CONSTRUCT {...}` e execute uma consulta `SELECT` com `explain` na segunda cláusula `WHERE {...}`. A avaliação da segunda cláusula `WHERE`, geralmente revela os principais desafios do processamento da consulta `CONSTRUCT`, pois as soluções do fluxo de saída da segunda `WHERE` no modelo `CONSTRUCT` geralmente exigem apenas substituição direta.

**Os operadores do explain podem ser alterados em versões futuras**  
Os operadores e parâmetros do `explain` do SPARQL podem ser alterados em versões futuras.

**A saída do explain pode ser alterada em versões futuras**  
Por exemplo, os cabeçalhos das colunas podem ser alterados e mais colunas podem ser adicionadas às tabelas.

# Consultas federadas do SPARQL no Neptune usando a extensão `SERVICE`
<a name="sparql-service"></a>

O Amazon Neptune é totalmente compatível com a extensão de consultas federadas do SPARQL que usa a palavra-chave `SERVICE`. (Para obter mais informações, consulte [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/).)

A palavra-chave `SERVICE` instrui o mecanismo de consulta do SPARQL a executar uma parte da consulta em um endpoint remoto do SPARQL e compor o resultado da consulta final. Somente operações `READ` são possíveis. As operações `WRITE` e `DELETE` não são compatíveis. O Neptune só pode executar consultas federadas em endpoints SPARQL acessíveis em sua nuvem privada virtual (VPC). No entanto, também é possível usar um proxy reverso na VPC para tornar uma fonte de dados externa acessível dentro da VPC.

**nota**  
Quando o `SERVICE` do SPARQL é usado para federar uma consulta em dois ou mais clusters do Neptune na mesma VPC, os grupos de segurança devem ser configurados para permitir que todos esses clusters do Neptune se comuniquem uns com os outros.

**Importante**  
A federação do SPARQL 1.1 faz solicitações de serviço em seu nome ao transmitir consultas e parâmetros para endpoints do SPARQL externos. É sua responsabilidade verificar se os endpoints do SPARQL externos atendem aos requisitos de segurança e tratamento de dados de seu aplicativo.

## Exemplo de consulta federada do Neptune
<a name="sparql-service-example-1"></a>

O exemplo simples a seguir mostra como funcionam as consultas federadas do SPARQL.

Suponha que um cliente envie a seguinte consulta ao *Neptune-1* em `http://neptune-1:8182/sparql`.

```
SELECT * WHERE {
   ?person rdf:type foaf:Person .
   SERVICE <http://neptune-2:8182/sparql> {
       ?person foaf:knows ?friend .
    }
}
```

1. O *Neptune-1* avalia o primeiro padrão de consulta (*Q-1*) que é `?person rdf:type foaf:Person`, usa os resultados para resolver `?person` em *Q-2* (`?person foaf:knows ?friend`) e encaminha o padrão resultante para o *Neptune-2* em `http://neptune-2:8182/sparql`.

1. O *Neptune-2* avalia *Q-2* e envia os resultados de volta ao *Neptune-1*.

1. *Neptune-1* une as soluções dos dois padrões e envia os resultados de volta ao cliente.

Esse fluxo é mostrado no diagrama a seguir.

![\[Diagrama do fluxo que mostra os padrões de consulta federada do SPARQL sendo avaliados e as respostas enviadas de volta ao cliente.\]](http://docs.aws.amazon.com/pt_br/neptune/latest/userguide/images/federated.png)


**nota**  
“Por padrão, o otimizador determina em que ponto da execução da consulta a instrução `SERVICE` é executada. É possível substituir esse posicionamento usando a dica de consulta [joinOrder](sparql-query-hints-joinOrder.md).

## Controle de acesso de consultas federadas no Neptune
<a name="sparql-service-auth"></a>

O Neptune AWS Identity and Access Management usa (IAM) para autenticação e autorização. O controle de acesso de uma consulta federada pode envolver mais de uma instância de banco de dados do Neptune. Essas instâncias podem ter requisitos diferentes de controle de acesso. Em determinadas circunstâncias, isso pode limitar sua capacidade de fazer uma consulta federada.

Considere o exemplo simples apresentado na seção anterior. *O Neptune-1* chama o *Neptune-2* com as mesmas credenciais com as quais ele foi chamado.
+ Se o *Neptune-1* exigir autenticação e autorização do IAM, mas o *Neptune-2* não exigir, bastará ter as permissões apropriadas do IAM para o *Neptune-1* para fazer a consulta federada.
+ Se o *Neptune-1* e o *Neptune-2* exigirem a autenticação e a autorização do IAM, você precisará associar as permissões do IAM para os dois bancos de dados para fazer a consulta federada. Os dois clusters também devem estar na mesma AWS conta e na mesma região. Atualmente, não há suporte para arquiteturas de consulta federada and/or entre contas entre regiões.
+ No entanto, quando o *Neptune-1* não estiver habilitado para o *Neptune-2*, você não poderá fazer uma consulta federada. O motivo é que o *Neptune-1* não pode recuperar suas credenciais do IAM e transmiti-las ao *Neptune-2* para autorizar a segunda parte da consulta.