This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch spec-1.1.0
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/spec-1.1.0 by this push:
new 6e2c0c6a feat: clarify progress
6e2c0c6a is described below
commit 6e2c0c6a6190a1b9d1590e32808fa227d9334a93
Author: David Li <[email protected]>
AuthorDate: Wed Aug 9 12:02:04 2023 -0400
feat: clarify progress
---
adbc.h | 20 +++++++++++++++++++-
go/adbc/adbc.go | 6 +-----
go/adbc/drivermgr/adbc.h | 20 +++++++++++++++++++-
.../org/apache/arrow/adbc/core/AdbcStatement.java | 9 +++++++++
4 files changed, 48 insertions(+), 7 deletions(-)
diff --git a/adbc.h b/adbc.h
index a2a33a4d..e6befb8b 100644
--- a/adbc.h
+++ b/adbc.h
@@ -604,7 +604,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct
ArrowArrayStream* stream
/// \brief The name of the option for getting the progress of a query.
///
-/// Progress is a value in [0.0, 1.0].
+/// The value is not necessarily in any particular range or have any
+/// particular units. (For example, it might be a percentage, bytes of data,
+/// rows of data, number of workers, etc.) The max value can be retrieved via
+/// ADBC_STATEMENT_OPTION_MAX_PROGRESS. This represents the progress of
+/// execution, not of consumption (i.e., it is independent of how much of the
+/// result set has been read by the client via ArrowArrayStream.get_next().)
///
/// The type is double.
///
@@ -612,6 +617,19 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct
ArrowArrayStream* stream
/// \since ADBC API revision 1.1.0
#define ADBC_STATEMENT_OPTION_PROGRESS "adbc.statement.exec.progress"
+/// \brief The name of the option for getting the maximum progress of a query.
+///
+/// This is the value of ADBC_STATEMENT_OPTION_PROGRESS for a completed query.
+/// If not supported, or if the value is nonpositive, then the maximum is not
+/// known. (For instance, the query may be fully streaming and the driver
+/// does not know when the result set will end.)
+///
+/// The type is double.
+///
+/// \see AdbcStatementGetOptionDouble
+/// \since ADBC API revision 1.1.0
+#define ADBC_STATEMENT_OPTION_MAX_PROGRESS "adbc.statement.exec.max_progress"
+
/// \brief The name of the canonical option for setting the isolation
/// level of a transaction.
///
diff --git a/go/adbc/adbc.go b/go/adbc/adbc.go
index 8f29c91b..ad6194f2 100644
--- a/go/adbc/adbc.go
+++ b/go/adbc/adbc.go
@@ -230,6 +230,7 @@ const (
OptionKeyIncremental = "adbc.statement.exec.incremental"
// Get the progress
OptionKeyProgress = "adbc.statement.exec.progress"
+ OptionKeyMaxProgress = "adbc.statement.exec.max_progress"
OptionKeyIngestTargetTable = "adbc.ingest.target_table"
OptionKeyIngestMode = "adbc.ingest.mode"
OptionKeyIsolationLevel =
"adbc.connection.transaction.isolation_level"
@@ -255,11 +256,6 @@ const (
LevelLinearizable OptionIsolationLevel =
"adbc.connection.transaction.isolation.linearizable"
)
-// Canonical property values
-const (
- PropertyProgress = "adbc.statement.exec.progress"
-)
-
// Standard statistic names and keys.
const (
// The dictionary-encoded name of the average byte width statistic.
diff --git a/go/adbc/drivermgr/adbc.h b/go/adbc/drivermgr/adbc.h
index a2a33a4d..e6befb8b 100644
--- a/go/adbc/drivermgr/adbc.h
+++ b/go/adbc/drivermgr/adbc.h
@@ -604,7 +604,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct
ArrowArrayStream* stream
/// \brief The name of the option for getting the progress of a query.
///
-/// Progress is a value in [0.0, 1.0].
+/// The value is not necessarily in any particular range or have any
+/// particular units. (For example, it might be a percentage, bytes of data,
+/// rows of data, number of workers, etc.) The max value can be retrieved via
+/// ADBC_STATEMENT_OPTION_MAX_PROGRESS. This represents the progress of
+/// execution, not of consumption (i.e., it is independent of how much of the
+/// result set has been read by the client via ArrowArrayStream.get_next().)
///
/// The type is double.
///
@@ -612,6 +617,19 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct
ArrowArrayStream* stream
/// \since ADBC API revision 1.1.0
#define ADBC_STATEMENT_OPTION_PROGRESS "adbc.statement.exec.progress"
+/// \brief The name of the option for getting the maximum progress of a query.
+///
+/// This is the value of ADBC_STATEMENT_OPTION_PROGRESS for a completed query.
+/// If not supported, or if the value is nonpositive, then the maximum is not
+/// known. (For instance, the query may be fully streaming and the driver
+/// does not know when the result set will end.)
+///
+/// The type is double.
+///
+/// \see AdbcStatementGetOptionDouble
+/// \since ADBC API revision 1.1.0
+#define ADBC_STATEMENT_OPTION_MAX_PROGRESS "adbc.statement.exec.max_progress"
+
/// \brief The name of the canonical option for setting the isolation
/// level of a transaction.
///
diff --git
a/java/core/src/main/java/org/apache/arrow/adbc/core/AdbcStatement.java
b/java/core/src/main/java/org/apache/arrow/adbc/core/AdbcStatement.java
index 07c7eab1..a1f9e0f3 100644
--- a/java/core/src/main/java/org/apache/arrow/adbc/core/AdbcStatement.java
+++ b/java/core/src/main/java/org/apache/arrow/adbc/core/AdbcStatement.java
@@ -143,6 +143,15 @@ public interface AdbcStatement extends AutoCloseable,
AdbcOptions {
throw AdbcException.notImplemented("Statement does not support
getProgress");
}
+ /**
+ * Get the upper bound of the progress.
+ *
+ * @since ADBC API revision 1.1.0
+ */
+ default double getMaxProgress() throws AdbcException {
+ throw AdbcException.notImplemented("Statement does not support
getMaxProgress");
+ }
+
/**
* Get the schema for bound parameters.
*
