Skip to content

Commit

Permalink
feat(java): implement 1.1.0 features (#872)
Browse files Browse the repository at this point in the history
- ADBC_INFO_DRIVER_ADBC_VERSION
- StatementExecuteSchema (#318)
- ADBC_CONNECTION_OPTION_CURRENT_{CATALOG, DB_SCHEMA} (#319)
- error_details (#755)
- GetStatistics (#685)
  • Loading branch information
lidavidm committed Jul 21, 2023
1 parent 6cfed4c commit d6a083c
Show file tree
Hide file tree
Showing 23 changed files with 1,110 additions and 56 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ enum GetObjectsDepth {
* <table border="1">
* <tr><th>Field Name</th> <th>Field Type</th> </tr>
* <tr><td>db_schema_name</td> <td>utf8</td> </tr>
* <tr><td>db_schema_tables</td> <td>list[TABLE_SCHEMA]</td> </tr>
* <tr><td>db_schema_statistics</td> <td>list[STATISTICS_SCHEMA]</td></tr>
* <caption>The definition of DB_SCHEMA_SCHEMA.</caption>
* </table>
*
Expand All @@ -268,7 +268,7 @@ enum GetObjectsDepth {
* <tr><th>Field Name</th> <th>Field Type</th> <th>Comments</th></tr>
* <tr><td>table_name</td> <td>utf8 not null</td> <td></td></tr>
* <tr><td>column_name</td> <td>utf8</td> <td>(1)</td></tr>
* <tr><td>statistic_key</td> <td>int16</td> <td>(2)</td></tr>
* <tr><td>statistic_key</td> <td>int16 not null</td> <td>(2)</td></tr>
* <tr><td>statistic_value</td> <td>VALUE_SCHEMA not null</td> <td></td></tr>
* <tr><td>statistic_is_approximate</td><td>bool not null</td> <td>(3)</td></tr>
* <caption>The definition of STATISTICS_SCHEMA.</caption>
Expand All @@ -291,7 +291,6 @@ enum GetObjectsDepth {
* <tr><td>int64</td> <td>int64</td> </td></tr>
* <tr><td>uint64</td> <td>uint64</td> </td></tr>
* <tr><td>float64</td> <td>float64</td> </td></tr>
* <tr><td>decimal256</td> <td>decimal256</td> </td></tr>
* <tr><td>binary</td> <td>binary</td> </td></tr>
* <caption>The definition of VALUE_SCHEMA.</caption>
* </table>
Expand All @@ -314,6 +313,18 @@ default ArrowReader getStatistics(
throw AdbcException.notImplemented("Connection does not support getStatistics()");
}

/**
* Get the names of additional statistics defined by this driver.
*
* <p>The result is an Arrow dataset with the following schema:
*
* <table border="1">
* <tr><th>Field Name</th> <th>Field Type</th> </tr>
* <tr><td>statistic_name</td> <td>utf8 not null</td> </tr>
* <tr><td>statistic_key</td> <td>int16 not null</td></tr>
* <caption>The definition of the GetStatistics result schema.</caption>
* </table>
*/
default ArrowReader getStatisticNames() throws AdbcException {
throw AdbcException.notImplemented("Connection does not support getStatisticNames()");
}
Expand Down Expand Up @@ -408,7 +419,7 @@ default String getCurrentDbSchema() throws AdbcException {
*
* @since ADBC API revision 1.1.0
*/
default void setCurrentDbSchema(String catalog) throws AdbcException {
default void setCurrentDbSchema(String dbSchema) throws AdbcException {
throw AdbcException.notImplemented("Connection does not support current catalog");
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ public interface AdbcDriver {
*
* @since ADBC API revision 1.1.0
*/
AdbcOptionKey<String> PARAM_PASSWORD = new AdbcOptionKey<>("password", String.class);
TypedKey<String> PARAM_PASSWORD = new TypedKey<>("password", String.class);

/**
* The standard parameter name for a connection URI (type String).
*
* @since ADBC API revision 1.1.0
*/
AdbcOptionKey<String> PARAM_URI = new AdbcOptionKey<>("uri", String.class);
TypedKey<String> PARAM_URI = new TypedKey<>("uri", String.class);

/**
* The standard parameter name for a connection URL (type String).
Expand All @@ -47,7 +47,7 @@ public interface AdbcDriver {
*
* @since ADBC API revision 1.1.0
*/
AdbcOptionKey<String> PARAM_USERNAME = new AdbcOptionKey<>("username", String.class);
TypedKey<String> PARAM_USERNAME = new TypedKey<>("username", String.class);

/** The standard parameter name for SQL quirks configuration (type SqlQuirks). */
String PARAM_SQL_QUIRKS = "adbc.sql.quirks";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@
*/
package org.apache.arrow.adbc.core;

import java.nio.ByteBuffer;
import java.util.Collection;
import java.util.Collections;

Expand All @@ -37,7 +36,7 @@ public class AdbcException extends Exception {
private final AdbcStatusCode status;
private final String sqlState;
private final int vendorCode;
private Collection<ByteBuffer> details;
private Collection<ErrorDetail> details;

public AdbcException(
String message, Throwable cause, AdbcStatusCode status, String sqlState, int vendorCode) {
Expand All @@ -50,7 +49,7 @@ public AdbcException(
AdbcStatusCode status,
String sqlState,
int vendorCode,
Collection<ByteBuffer> details) {
Collection<ErrorDetail> details) {
super(message, cause);
this.status = status;
this.sqlState = sqlState;
Expand Down Expand Up @@ -94,14 +93,14 @@ public int getVendorCode() {
}

/**
* Get extra driver-specific binary error details.
* Get extra driver-specific error details.
*
* <p>This allows drivers to return custom, structured error information (for example, JSON or
* Protocol Buffers) that can be optionally parsed by clients, beyond the standard AdbcError
* fields, without having to encode it in the error message. The encoding of the data is
* driver-defined.
*/
public Collection<ByteBuffer> getDetails() {
public Collection<ErrorDetail> getDetails() {
return details;
}

Expand All @@ -115,7 +114,7 @@ public AdbcException withCause(Throwable cause) {
/**
* Copy this exception with different details (a convenience for use with the static factories).
*/
public AdbcException withDetails(Collection<ByteBuffer> details) {
public AdbcException withDetails(Collection<ErrorDetail> details) {
return new AdbcException(getMessage(), getCause(), status, sqlState, vendorCode, details);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ public interface AdbcOptions {
* @return The option value.
* @param <T> The option value type.
*/
default <T> T getOption(AdbcOptionKey<T> key) throws AdbcException {
default <T> T getOption(TypedKey<T> key) throws AdbcException {
throw AdbcException.notImplemented("Unsupported option " + key);
}

Expand All @@ -39,7 +39,7 @@ default <T> T getOption(AdbcOptionKey<T> key) throws AdbcException {
* @param value The option value.
* @param <T> The option value type.
*/
default <T> void setOption(AdbcOptionKey<T> key, T value) throws AdbcException {
default <T> void setOption(TypedKey<T> key, T value) throws AdbcException {
throw AdbcException.notImplemented("Unsupported option " + key);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ default void cancel() throws AdbcException {
/**
* Set a generic query option.
*
* @deprecated Prefer {@link #setOption(AdbcOptionKey, Object)}.
* @deprecated Prefer {@link #setOption(TypedKey, Object)}.
*/
default void setOption(String key, Object value) throws AdbcException {
throw AdbcException.notImplemented("Unsupported option " + key);
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.arrow.adbc.core;

import java.util.Objects;

/** Additional details (not necessarily human-readable) contained in an {@link AdbcException}. */
public class ErrorDetail {
private final String key;
private final Object value;

public ErrorDetail(String key, Object value) {
this.key = Objects.requireNonNull(key);
this.value = Objects.requireNonNull(value);
}

public String getKey() {
return key;
}

public Object getValue() {
return value;
}

@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
ErrorDetail that = (ErrorDetail) o;
return Objects.equals(getKey(), that.getKey()) && Objects.equals(getValue(), that.getValue());
}

@Override
public int hashCode() {
return Objects.hash(getKey(), getValue());
}

@Override
public String toString() {
return "ErrorDetail{" + "key='" + key + '\'' + ", value=" + value + '}';
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import org.apache.arrow.vector.types.FloatingPointPrecision;
import org.apache.arrow.vector.types.Types;
import org.apache.arrow.vector.types.UnionMode;
import org.apache.arrow.vector.types.pojo.ArrowType;
import org.apache.arrow.vector.types.pojo.Field;
Expand All @@ -30,10 +32,13 @@ private StandardSchemas() {
throw new AssertionError("Do not instantiate this class");
}

private static final ArrowType INT16 = new ArrowType.Int(16, true);
private static final ArrowType INT32 = new ArrowType.Int(32, true);
private static final ArrowType INT64 = new ArrowType.Int(64, true);
private static final ArrowType INT16 = Types.MinorType.SMALLINT.getType();
private static final ArrowType INT32 = Types.MinorType.INT.getType();
private static final ArrowType INT64 = Types.MinorType.BIGINT.getType();
private static final ArrowType UINT32 = new ArrowType.Int(32, false);
private static final ArrowType UINT64 = new ArrowType.Int(64, false);
private static final ArrowType FLOAT64 =
new ArrowType.FloatingPoint(FloatingPointPrecision.DOUBLE);

/** The schema of the result set of {@link AdbcConnection#getInfo(int[])}}. */
public static final Schema GET_INFO_SCHEMA =
Expand Down Expand Up @@ -83,11 +88,11 @@ private StandardSchemas() {
Field.notNullable("constraint_type", ArrowType.Utf8.INSTANCE),
new Field(
"constraint_column_names",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(Field.nullable("item", new ArrowType.Utf8()))),
new Field(
"constraint_column_usage",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field("item", FieldType.nullable(ArrowType.Struct.INSTANCE), USAGE_SCHEMA))));

Expand Down Expand Up @@ -119,12 +124,12 @@ private StandardSchemas() {
new Field("table_type", FieldType.notNullable(ArrowType.Utf8.INSTANCE), null),
new Field(
"table_columns",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field("item", FieldType.nullable(ArrowType.Struct.INSTANCE), COLUMN_SCHEMA))),
new Field(
"table_constraints",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field(
"item", FieldType.nullable(ArrowType.Struct.INSTANCE), CONSTRAINT_SCHEMA))));
Expand All @@ -134,20 +139,76 @@ private StandardSchemas() {
new Field("db_schema_name", FieldType.notNullable(ArrowType.Utf8.INSTANCE), null),
new Field(
"db_schema_tables",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field("item", FieldType.nullable(ArrowType.Struct.INSTANCE), TABLE_SCHEMA))));

/**
* The schema of the result of {@link AdbcConnection#getObjects(AdbcConnection.GetObjectsDepth,
* String, String, String, String[], String)}.
*/
public static final Schema GET_OBJECTS_SCHEMA =
new Schema(
Arrays.asList(
new Field("catalog_name", FieldType.notNullable(ArrowType.Utf8.INSTANCE), null),
new Field(
"catalog_db_schemas",
FieldType.notNullable(ArrowType.List.INSTANCE),
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field(
"item",
FieldType.nullable(ArrowType.Struct.INSTANCE),
DB_SCHEMA_SCHEMA)))));

public static final List<Field> STATISTICS_VALUE_SCHEMA =
Arrays.asList(
Field.nullable("int64", INT64),
Field.nullable("uint64", UINT64),
Field.nullable("float64", FLOAT64),
Field.nullable("binary", ArrowType.Binary.INSTANCE));

public static final List<Field> STATISTICS_SCHEMA =
Arrays.asList(
Field.notNullable("table_name", ArrowType.Utf8.INSTANCE),
Field.nullable("column_name", ArrowType.Utf8.INSTANCE),
Field.notNullable("statistic_key", INT16),
new Field(
"statistic_value",
FieldType.notNullable(new ArrowType.Union(UnionMode.Dense, new int[] {0, 1, 2, 3})),
STATISTICS_VALUE_SCHEMA),
Field.notNullable("statistic_is_approximate", ArrowType.Bool.INSTANCE));

public static final List<Field> STATISTICS_DB_SCHEMA_SCHEMA =
Arrays.asList(
new Field("db_schema_name", FieldType.notNullable(ArrowType.Utf8.INSTANCE), null),
new Field(
"db_schema_statistics",
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field(
"item", FieldType.nullable(ArrowType.Struct.INSTANCE), STATISTICS_SCHEMA))));

/**
* The schema of the result of {@link AdbcConnection#getStatistics(String, String, String,
* boolean)}.
*/
public static final Schema GET_STATISTICS_SCHEMA =
new Schema(
Arrays.asList(
new Field("catalog_name", FieldType.notNullable(ArrowType.Utf8.INSTANCE), null),
new Field(
"catalog_db_schemas",
FieldType.nullable(ArrowType.List.INSTANCE),
Collections.singletonList(
new Field(
"item",
FieldType.nullable(ArrowType.Struct.INSTANCE),
STATISTICS_DB_SCHEMA_SCHEMA)))));

/** The schema of the result of {@link AdbcConnection#getStatisticNames()}. */
public static final Schema GET_STATISTIC_NAMES_SCHEMA =
new Schema(
Arrays.asList(
Field.notNullable("statistic_name", ArrowType.Utf8.INSTANCE),
Field.notNullable("statistic_name", INT16)));
}
Loading

0 comments on commit d6a083c

Please sign in to comment.