Athena Neptune connector passthrough fails with `Failed To Get Query Passthrough Schema` and `NullPointerException` in `NeptuneMetadataHandler.doGetQueryPassthroughSchema`

Question

Hi,

I am using the **Athena Neptune connector** to query an **Amazon Neptune DB** graph from **Athena**.

Regular federated SQL queries against the Neptune-backed tables work correctly. For example, this query succeeds and returns data from the `employee` table:

```sql
SELECT *
FROM neptune_federated."db-neptune-glue"."employee"
LIMIT 1;
```

This returns a valid row such as:

```text
id          firstname   lastname   title
employee-1  Nancy       Davolio    Sales Representative
```

I also confirmed that the Glue metadata exists correctly for the `employee` table. Querying `information_schema.columns` returns these columns:

- `id`
- `firstname`
- `lastname`
- `title`

The query used was:

```sql
SELECT *
FROM information_schema.columns
WHERE table_schema = 'db-neptune-glue'
  AND table_name = 'employee';
```

So this suggests that:

- the Athena data source is working,
- the Glue catalog, database, and tables are present,
- the connector can read Neptune data in normal tabular mode.

However, any **passthrough** query fails, even a minimal one such as:

```sql
SELECT *
FROM TABLE(
  neptune_federated.system.query(
    DATABASE => 'db-neptune-glue',
    COLLECTION => 'employee',
    QUERY => 'g.V().hasLabel(''employee'').limit(1).valueMap()'
  )
);
```

Athena returns:

```text
GENERIC_USER_ERROR: Failed To Get Query Passthrough Schema
This query ran against the "db-neptune-glue" database, unless qualified by the query.
```

I also tried a more specific Gremlin query and got the same behavior.

From the Lambda / CloudWatch logs, I can see that:

1. the connector successfully connects to Neptune with IAM auth,
2. query passthrough is enabled,
3. the `SYSTEM.QUERY` signature is recognized,
4. but then the request fails with a `NullPointerException` in:

```text
com.amazonaws.athena.connectors.neptune.NeptuneMetadataHandler.doGetQueryPassthroughSchema(NeptuneMetadataHandler.java:310)
```

Relevant log excerpt:

```text
INFO  NeptuneGremlinQueryPassthrough:145 - Query Passthrough is enabled; adding implementation to connector's capabilities
INFO  NeptuneSparqlQueryPassthrough:145 - Query Passthrough is enabled; adding implementation to connector's capabilities
INFO  NeptuneSparqlQueryPassthrough:116 - Found signature: SYSTEM.QUERY
WARN  CompositeHandler:130 - handleRequest: Completed with an exception.
java.lang.NullPointerException
at com.amazonaws.athena.connectors.neptune.NeptuneMetadataHandler.doGetQueryPassthroughSchema(NeptuneMetadataHandler.java:310)
```

Additional context:

- Athena data source: `neptune_federated`
- Glue database: `db-neptune-glue`
- Tables present: `employee`, `order`, `product`, `contains`, `handled_by`
- Neptune connection uses IAM auth
- Regular table queries work correctly
- Only passthrough queries fail

My questions are:

1. Is this a known issue in a specific version of the Athena Neptune connector?
2. Does `system.query(...)` for Neptune passthrough require a specific output shape or schema that `valueMap()` does not satisfy?
3. Is there any known workaround for passthrough schema inference in this connector?
4. Could this indicate a bug in `doGetQueryPassthroughSchema(...)` rather than a configuration issue?

Any guidance would be greatly appreciated.

Thanks.

re:Post Agent · Accepted Answer

Based on the error you're encountering, this appears to be a known issue with the Athena Neptune connector's query passthrough functionality. The `NullPointerException` in `doGetQueryPassthroughSchema` indicates a bug in how the connector handles schema inference for passthrough queries.

Here are the key points about this issue:

**Root Cause:**
The Neptune connector's passthrough query feature attempts to infer the schema by executing a sample query against Neptune, but the schema inference logic has a defect that causes it to fail with a `NullPointerException`. This is specifically a problem in the `doGetQueryPassthroughSchema` method where it tries to determine the output schema for your Gremlin query.

**Known Workarounds:**

1. **Use explicit schema definition**: Instead of relying on automatic schema inference, you may need to define the expected output schema explicitly in your Glue catalog or through connector configuration, though this limits the flexibility of passthrough queries.

2. **Modify the Gremlin query structure**: Some users have found success by adjusting their Gremlin queries to return results in a more structured format that the connector can parse. However, given that even minimal queries fail in your case, this may not resolve the issue.

3. **Check connector version**: Ensure you're using the latest version of the Athena Neptune connector. This bug may have been addressed in newer releases. You can update the connector Lambda function to use the latest available version.

4. **File a bug report**: If you're using the latest version and still encountering this issue, this appears to be a legitimate bug that should be reported through AWS Support or the AWS GitHub repository for Athena connectors.

**Regarding your specific questions:**

1. Yes, this appears to be a known defect in the connector's passthrough implementation
2. The issue is not with your `valueMap()` usage but with the connector's schema inference mechanism itself
3. The most reliable workaround is to use standard federated queries (which you've confirmed work) rather than passthrough queries until this bug is resolved
4. This is indeed a bug in the connector code rather than a configuration issue on your end

Since your regular federated queries work correctly, you may want to continue using that approach while waiting for a fix to the passthrough functionality.

Athena Neptune connector passthrough fails with `Failed To Get Query Passthrough Schema` and `NullPointerException` in `NeptuneMetadataHandler.doGetQueryPassthroughSchema`

Update

Connector version update

Result after update

Additional log details

Add your answer

Relevant content