public interface Client
A Client that connects to one or more nodes in a volt cluster
and provides methods for invoking stored procedures and receiving
responses.
Each client instance is backed by a single thread that is responsible for writing requests and reading responses from the network as well as invoking callbacks for stored procedures that are invoked asynchronously. There is an upper limit on the capacity of a single client instance and it may be necessary to use a pool of instances to get the best throughput and latency. If a heavyweight client instance is requested it will be backed by multiple threads, but under the current implementation it is better to us multiple single threaded instances
Because callbacks are invoked directly on the network thread the performance of the client is sensitive to the amount of work and blocking done in callbacks. If there is any question about whether callbacks will block or take a long time then an application should have callbacks hand off processing to an application controlled thread pool.
| Modifier and Type | Field and Description |
|---|---|
static int |
VOLTDB_SERVER_PORT
Default non-admin port number for volt cluster instances.
|
| Modifier and Type | Method and Description |
|---|---|
void |
backpressureBarrier()
Deprecated.
The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
|
boolean |
blocking()
Deprecated.
The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
|
int |
calculateInvocationSerializedSize(java.lang.String procName,
java.lang.Object... parameters)
Deprecated.
because hinting at the serialized size no longer has any effect.
|
boolean |
callAllPartitionProcedure(AllPartitionProcedureCallback callback,
java.lang.String procedureName,
java.lang.Object... params)
The method uses system procedure @GetPartitionKeys to get a set of partition values which are used to reach every partition, and then asynchronously
executes the stored procedure across partitions.
|
ClientResponseWithPartitionKey[] |
callAllPartitionProcedure(java.lang.String procedureName,
java.lang.Object... params)
The method uses system procedure @GetPartitionKeys to get a set of partition values and then execute the stored procedure
one partition at a time, and return an aggregated response.
|
boolean |
callProcedure(ProcedureCallback callback,
int expectedSerializedSize,
java.lang.String procName,
java.lang.Object... parameters)
Deprecated.
because hinting at the serialized size no longer has any effect.
|
boolean |
callProcedure(ProcedureCallback callback,
java.lang.String procName,
java.lang.Object... parameters)
Asynchronously invoke a replicated procedure, by providing a callback that will be invoked by the single
thread backing the client instance when the procedure invocation receives a response.
|
ClientResponse |
callProcedure(java.lang.String procName,
java.lang.Object... parameters)
Synchronously invoke a procedure.
|
ClientResponse |
callProcedureWithTimeout(int queryTimeout,
java.lang.String procName,
java.lang.Object... parameters)
Synchronously invoke a procedure with timeout.
|
boolean |
callProcedureWithTimeout(ProcedureCallback callback,
int queryTimeout,
java.lang.String procName,
java.lang.Object... parameters)
Asynchronously invoke a replicated procedure with timeout, by providing a callback that will be invoked by
the single thread backing the client instance when the procedure invocation receives a response.
|
void |
close()
Shutdown this Client, closing all network connections and release all memory resources.
|
void |
configureBlocking(boolean blocking)
Deprecated.
The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
|
void |
createConnection(java.lang.String host)
Create a connection to a VoltDB node and add it to the set of connections.
|
void |
createConnection(java.lang.String host,
int port)
Create a connection to a VoltDB node and add it to the set of connections.
|
ClientStatsContext |
createStatsContext()
Get a
ClientStatsContext instance to fetch and process performance
statistics. |
void |
drain()
Block the current thread until all queued stored procedure invocations have received responses
or there are no more connections to the cluster.
|
java.lang.String |
getBuildString()
Retrieve the build string that was provided by the server at connection time.
|
java.util.List<java.net.InetSocketAddress> |
getConnectedHostList()
Get the list of VoltDB server hosts that this client has open TCP connections
to.
|
java.lang.Object[] |
getInstanceId()
Get an identifier for the cluster that this client is currently connected to.
|
org.voltdb.client.VoltBulkLoader.VoltBulkLoader |
getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
boolean upsert,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback)
Creates a new instance of a VoltBulkLoader that is bound to this Client.
|
org.voltdb.client.VoltBulkLoader.VoltBulkLoader |
getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
boolean upsertMode,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback,
org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback)
Creates a new instance of a VoltBulkLoader that is bound to this Client.
|
org.voltdb.client.VoltBulkLoader.VoltBulkLoader |
getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) |
int[] |
getThroughputAndOutstandingTxnLimits()
Get the instantaneous values of the rate limiting values for this client.
|
boolean |
isAutoReconnectEnabled()
Tell whether Client has turned on the auto-reconnect feature.
|
ClientResponse |
updateApplicationCatalog(java.io.File catalogPath,
java.io.File deploymentPath)
Deprecated.
|
boolean |
updateApplicationCatalog(ProcedureCallback callback,
java.io.File catalogPath,
java.io.File deploymentPath)
Deprecated.
|
ClientResponse |
updateClasses(java.io.File jarPath,
java.lang.String classesToDelete)
Synchronously invokes UpdateClasses procedure.
|
boolean |
updateClasses(ProcedureCallback callback,
java.io.File jarPath,
java.lang.String classesToDelete)
Asynchronously invokes UpdateClasses procedure.
|
void |
writeSummaryCSV(ClientStats stats,
java.lang.String path)
Write a single line of comma separated values to the file specified.
|
void |
writeSummaryCSV(java.lang.String statsRowName,
ClientStats stats,
java.lang.String path)
Write a single line of comma separated values to the file specified.
|
static final int VOLTDB_SERVER_PORT
void createConnection(java.lang.String host)
throws java.net.UnknownHostException,
java.io.IOException
Create a connection to a VoltDB node and add it to the set of connections.
This is a synchronous operation.
host - Hostname or IP address of the host to connect to including
optional port in the hostname:port format.java.net.UnknownHostException - if the hostname can't be resolved.java.io.IOException - if there is a Java network or connection problem.void createConnection(java.lang.String host,
int port)
throws java.net.UnknownHostException,
java.io.IOException
Create a connection to a VoltDB node and add it to the set of connections.
This is a synchronous operation.
host - Hostname or IP address of the host to connect to.port - Port number on remote host to connect to.java.net.UnknownHostException - if the hostname can't be resolved.java.io.IOException - if there is a Java network or connection problem.ClientResponse callProcedure(java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException, ProcCallException
Synchronously invoke a procedure. Blocks until a result is available. A ProcCallException
is thrown if the response is anything other then success.
procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.ClientResponse instance of procedure call results.ProcCallException - on any VoltDB specific failure.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.boolean callProcedure(ProcedureCallback callback, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
Asynchronously invoke a replicated procedure, by providing a callback that will be invoked by the single
thread backing the client instance when the procedure invocation receives a response.
See the Client class documentation for information on the negative performance impact of slow or
blocking callbacks. If there is backpressure
this call will block until the invocation is queued. If configureBlocking(false) is invoked
then it will return immediately. Check the return value to determine if queueing actually took place.
A false return, meaning that the procedure call was not queued, implicitly indicates
that no ClientResponse has been delivered to the callback.
callback - ProcedureCallback that will be invoked with procedure results.procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.true if the procedure was queued and false otherwise.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.ClientResponse callProcedureWithTimeout(int queryTimeout, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException, ProcCallException
Synchronously invoke a procedure with timeout. Blocks until a result is available. A ProcCallException
is thrown if the response is anything other then success.
WARNING: Use of a queryTimeout value that is greater than the global timeout value for your VoltDB configuration will temporarily override that safeguard. Currently, non-privileged users (requiring only SQLREAD permissions) can invoke this method, potentially degrading system performance with an uncontrolled long-running procedure.
queryTimeout - query batch timeout setting in milliseconds of queries in a batch for read only procedures.procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.ClientResponse instance of procedure call results.ProcCallException - on any VoltDB specific failure.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.boolean callProcedureWithTimeout(ProcedureCallback callback, int queryTimeout, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
Asynchronously invoke a replicated procedure with timeout, by providing a callback that will be invoked by
the single thread backing the client instance when the procedure invocation receives a response.
See the Client class documentation for information on the negative performance impact of slow or
blocking callbacks. If there is backpressure
this call will block until the invocation is queued. If configureBlocking(false) is invoked
then it will return immediately. Check the return value to determine if queueing actually took place.
A false return, meaning that the procedure call was not queued, implicitly indicates
that no ClientResponse has been delivered to the callback.
WARNING: Use of a queryTimeout value that is greater than the global timeout value for your VoltDB configuration will temporarily override that safeguard. Currently, non-privileged users (requiring only SQLREAD permissions) can invoke this method, potentially degrading system performance with an uncontrolled long-running procedure.
callback - ProcedureCallback that will be invoked with procedure results.queryTimeout - query batch timeout setting in milliseconds of queries in a batch for read only procedures.procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.true if the procedure was queued and false otherwise.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.@Deprecated boolean callProcedure(ProcedureCallback callback, int expectedSerializedSize, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
Asynchronously invoke a replicated procedure. If there is backpressure this call will block until the invocation is queued. If configureBlocking(false) is invoked then it will return immediately. Check the return value to determine if queuing actually took place.
An opportunity is provided to hint what the size of the invocation
will be once serialized. This is used to perform more efficient memory allocation and serialization. The size
of an invocation can be calculated using calculateInvocationSerializedSize(String, Object...).
Only Clients that are resource constrained or expect to process hundreds of thousands of txns/sec will benefit
from accurately determining the serialized size of message.
callback - ProcedureCallback that will be invoked with procedure results.procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.expectedSerializedSize - A hint indicating the size the procedure invocation is expected to be
once serialized. Allocations are done in powers of two.true if the procedure was queued and false otherwise.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.@Deprecated
int calculateInvocationSerializedSize(java.lang.String procName,
java.lang.Object... parameters)
Calculate the size of a stored procedure invocation once it is serialized. This is computationally intensive as the invocation is serialized as part of the calculation.
procName - class name (not qualified by package) of the procedure to execute.parameters - vararg list of procedure's parameter values.@Deprecated ClientResponse updateApplicationCatalog(java.io.File catalogPath, java.io.File deploymentPath) throws java.io.IOException, NoConnectionsException, ProcCallException
Synchronously invokes UpdateApplicationCatalog procedure. Blocks until a
result is available. A ProcCallException is thrown if the
response is anything other then success.
Deprecated to be removed in 8.0. Note, you can still call the UpdateApplicationCatalog
system procedure directly using the callProcedure(String, Object...) family of
methods.
This method is a convenience method that is equivalent to reading the catalog
file into a byte array in Java code, then calling callProcedure(String, Object...)
with "@UpdateApplicationCatalog" as the procedure name, followed by the bytes of the catalog
and the string value of the deployment file.
catalogPath - Path to the catalog jar file.deploymentPath - Path to the deployment file.ClientResponse instance of procedure call results.java.io.IOException - If the files cannot be serialized or if there is a Java network error.NoConnectionsException - if this Client instance is not connected to any servers.ProcCallException - on any VoltDB specific failure.@Deprecated boolean updateApplicationCatalog(ProcedureCallback callback, java.io.File catalogPath, java.io.File deploymentPath) throws java.io.IOException, NoConnectionsException
Asynchronously invokes UpdateApplicationCatalog procedure. Does not guarantee that the invocation is actually queued. If there is backpressure on all connections to the cluster then the invocation will not be queued. Check the return value to determine if queuing actually took place.
Deprecated to be removed in 8.0. Note, you can still call the UpdateApplicationCatalog
system procedure directly using the callProcedure(String, Object...) family of
methods.
This method is a convenience method that is equivalent to reading the catalog
file into a byte array in Java code, then calling
callProcedure(ProcedureCallback, String, Object...) with
"@UpdateApplicationCatalog" as the procedure name, followed by the bytes of the catalog
and the string value of the deployment file.
callback - ProcedureCallback that will be invoked with procedure results.catalogPath - Path to the catalog jar file.deploymentPath - Path to the deployment file.true if the procedure was queued and false otherwise.java.io.IOException - If the files cannot be serialized or if there is a Java network error.NoConnectionsException - if this Client instance is not connected to any servers.ClientResponse updateClasses(java.io.File jarPath, java.lang.String classesToDelete) throws java.io.IOException, NoConnectionsException, ProcCallException
Synchronously invokes UpdateClasses procedure. Blocks until a
result is available. A ProcCallException is thrown if the
response is anything other then success.
This method is a convenience method that is equivalent to reading a jarfile containing
to be added/updated into a byte array in Java code, then calling
callProcedure(String, Object...)
with "@UpdateClasses" as the procedure name, followed by the bytes of the jarfile
and a string containing a comma-separates list of classes to delete from the catalog.
jarPath - Path to the jar file containing new/updated classes.classesToDelete - comma-separated list of classes to delete.ClientResponse instance of procedure call results.java.io.IOException - If the files cannot be serialized or if there is a Java network error.NoConnectionsException - if this Client instance is not connected to any servers.ProcCallException - on any VoltDB specific failure.boolean updateClasses(ProcedureCallback callback, java.io.File jarPath, java.lang.String classesToDelete) throws java.io.IOException, NoConnectionsException
Asynchronously invokes UpdateClasses procedure. Does not guarantee that the invocation is actually queued. If there is backpressure on all connections to the cluster then the invocation will not be queued. Check the return value to determine if queuing actually took place.
This method is a convenience method that is equivalent to reading a jarfile containing
to be added/updated into a byte array in Java code, then calling
callProcedure(ProcedureCallback, String, Object...)
with "@UpdateClasses" as the procedure name, followed by the bytes of the jarfile
and a string containing a comma-separates list of classes to delete from the catalog.
callback - ProcedureCallback that will be invoked with procedure results.jarPath - Path to the jar file containing new/updated classes. May be null.classesToDelete - comma-separated list of classes to delete. May be null.true if the procedure was queued and false otherwise.java.io.IOException - If the files cannot be serialized or if there is a Java network error.NoConnectionsException - if this Client instance is not connected to any servers.void drain()
throws NoConnectionsException,
java.lang.InterruptedException
Block the current thread until all queued stored procedure invocations have received responses or there are no more connections to the cluster.
NoConnectionsException - never, this is deprecated behavior, declared only for backward compatibility.java.lang.InterruptedException - if this blocking call is interrupted.void close()
throws java.lang.InterruptedException
Shutdown this Client, closing all network connections and release all memory resources.
Failing to call this method before the Client is garbage collected can generate errors because
finalization is used to detect resource leaks. A client cannot be used once it has
been closed.
java.lang.InterruptedException - if call is interrupted before it finishes.@Deprecated
void backpressureBarrier()
throws java.lang.InterruptedException
Blocks the current thread until there is no more backpressure or there are no more connections to the database
java.lang.InterruptedException - if this blocking call is interrupted.ClientStatsContext createStatsContext()
Get a ClientStatsContext instance to fetch and process performance
statistics. Each instance is linked to this client, but provides a custom
view of statistics for a desired time period.
ClientStatsContextjava.lang.Object[] getInstanceId()
Get an identifier for the cluster that this client is currently connected to. This will be null if the client has not been connected. Currently these values have logical meaning, but they should just be interpreted as a unique per-cluster value.
java.lang.String getBuildString()
Retrieve the build string that was provided by the server at connection time.
@Deprecated void configureBlocking(boolean blocking)
The default behavior for queueing of asynchronous procedure invocations is to block until it is possible to queue the invocation. If blocking is set to false, an async callProcedure will always return immediately if it is not possible to queue the procedure invocation due to backpressure. There is no effect on the synchronous variants of callProcedure.
blocking - Whether you want procedure calls to block on backpressure.@Deprecated boolean blocking()
Will callProcedure(ProcedureCallback, String, Object...) block
if an async procedure invocation could not be queued due to backpressure?
callProcedure(ProcedureCallback, String, Object...) will
block until backpressure ceases and false otherwise.int[] getThroughputAndOutstandingTxnLimits()
Get the instantaneous values of the rate limiting values for this client.
java.util.List<java.net.InetSocketAddress> getConnectedHostList()
Get the list of VoltDB server hosts that this client has open TCP connections to. Note that this doesn't guarantee that those nodes are actually alive at the precise moment this method is called. There is also a race condition between calling this method and acting on the results.
InetSocketAddress representing the connected hosts.boolean isAutoReconnectEnabled()
Tell whether Client has turned on the auto-reconnect feature. If it is on, Client would pause instead of stop when all connections to the server are lost, and would resume after the connection is restored.
void writeSummaryCSV(java.lang.String statsRowName,
ClientStats stats,
java.lang.String path)
throws java.io.IOException
Write a single line of comma separated values to the file specified. Used mainly for collecting results from benchmarks.
The format of this output is subject to change between versions
Format:
ClientStats instance, stats.ClientStats instance
until this call in ms.statsRowName - give the client stats row an identifiable name.stats - ClientStats instance with relevant stats.path - Path to write to, passed to FileWriter.FileWriter(String).java.io.IOException - on any file write error.void writeSummaryCSV(ClientStats stats, java.lang.String path) throws java.io.IOException
Write a single line of comma separated values to the file specified. Used mainly for collecting results from benchmarks.
The format of this output is subject to change between versions
Format:
ClientStats instance, stats.ClientStats instance
until this call in ms.stats - ClientStats instance with relevant stats.path - Path to write to, passed to FileWriter.FileWriter(String).java.io.IOException - on any file write error.org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
boolean upsert,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback)
throws java.lang.Exception
Creates a new instance of a VoltBulkLoader that is bound to this Client. Multiple instances of a VoltBulkLoader created by a single Client will share some resources, particularly if they are inserting into the same table.
tableName - Name of table that bulk inserts are to be applied to.maxBatchSize - Batch size to collect for the table before pushing a bulk insert.upsert - set to true if want upsert instead of insertfailureCallback - Callback procedure used for notification any failures.java.lang.Exception - if tableName can't be found in the catalog.org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback)
throws java.lang.Exception
java.lang.Exceptionorg.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
boolean upsertMode,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback,
org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback)
throws java.lang.Exception
Creates a new instance of a VoltBulkLoader that is bound to this Client. Multiple instances of a VoltBulkLoader created by a single Client will share some resources, particularly if they are inserting into the same table.
tableName - Name of table that bulk inserts are to be applied to.maxBatchSize - Batch size to collect for the table before pushing a bulk insert.upsertMode - set to true if want upsert instead of insertfailureCallback - Callback procedure used for notification any failures.successCallback - Callback for notifications on successful load operations.java.lang.Exception - if tableName can't be found in the catalog.ClientResponseWithPartitionKey[] callAllPartitionProcedure(java.lang.String procedureName, java.lang.Object... params) throws java.io.IOException, NoConnectionsException, ProcCallException
The method uses system procedure @GetPartitionKeys to get a set of partition values and then execute the stored procedure one partition at a time, and return an aggregated response. Blocks until results are available.
The set of partition values is cached to avoid repeated requests to fetch them. However the database partitions may be changed. The cached set of partition values will
be updated when the client affinity feature ClientConfig.setClientAffinity(boolean) is enabled and database cluster topology is updated.
If the client affinity is not enabled, the cached set of partition values will be synchronized with the database if the cached set is more than 1 second old. The database partitions are usually pretty static.
But when the cached set of partition values is out sync with the database, a procedure execution may be routed to a partition zero time or multiple times, exactly once per partition will not be guaranteed.
There may be undesirable impact on latency and throughput as a result of running a multi-partition procedure. This is particularly true for longer running procedures. Using multiple, smaller procedures can also help reducing latency and increasing throughput, for queries that modify large volumes of data, such as large deletes. For example, multiple smaller single partition procedures are particularly useful to age out large stale data where strong global consistency is not required.
When creating a single-partitioned procedure, you can use PARAMETER clause to specify the partitioning parameter which is used to determine the target partition.
The PARAMETER should not be specified in the stored procedure used in this call since the stored procedure will be executed on every partition. If you only want to
execute the procedure in the partition as designated with PARAMETER, use callProcedure(String, Object...) instead.
When creating a class stored procedure, the first argument in the procedure's run method must be the partition key, which matches the partition column type, followed by the
parameters as declared in the procedure. The argument partition key, not part of procedure's parameters, is assigned during the iteration of the partition set.
Example: A stored procedure with a parameter of long type and partition column of string type
CREATE TABLE tableWithStringPartition (id bigint NOT NULL,value_string varchar(50) NOT NULL,
value1 bigint NOT NULL,value2 bigint NOT NULL);
PARTITION TABLE tableWithStringPartition ON COLUMN value_string;
CREATE PROCEDURE FROM CLASS example.Everywhere;
PARTITION PROCEDURE Everywhere ON TABLE tableWithStringPartition COLUMN value_string;
public class Everywhere extends VoltProcedure {
public final SQLStmt stmt = new SQLStmt("SELECT count(*) FROM tableWithStringPartition where value1 > ?;");
public VoltTable[] run(String partitionKey, long value1) {
voltQueueSQL(stmt, value1);
return voltExecuteSQL(true);
}
}
The execution of the stored procedure may fail on one or more partitions. Thus check the status of the response on every partition.
procedureName - class name (not qualified by package) of the partitioned java procedure to execute.params - vararg list of procedure's parameter values.ClientResponseWithPartitionKey instances of procedure call results.ProcCallException - on any VoltDB specific failure.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.boolean callAllPartitionProcedure(AllPartitionProcedureCallback callback, java.lang.String procedureName, java.lang.Object... params) throws java.io.IOException, NoConnectionsException, ProcCallException
The method uses system procedure @GetPartitionKeys to get a set of partition values which are used to reach every partition, and then asynchronously executes the stored procedure across partitions. When results return from all partitions, the provided callback will be invoked. If there is backpressure, a call to a partition will block until the invocation on the partition is queued. If configureBlocking(false) is invoked then the execution on the partition will return immediately. Check the return values to determine if queueing actually took place on each partition.
The set of partition values is cached to avoid repeated requests to fetch them. However the database partitions may be changed. The cached set of partition values will
be updated when the client affinity feature ClientConfig.setClientAffinity(boolean) is enabled and database cluster topology is updated.
If the client affinity is not enabled, the cached set of partition values will be synchronized with the database if the cached set is more than 1 second old. The database partitions are usually pretty static.
But when the cached set of partition values is out sync with the database, a procedure execution may be routed to a partition zero time or multiple times, exactly once per partition will not be guaranteed.
There may be undesirable impact on latency and throughput as a result of running a multi-partition procedure. This is particularly true for longer running procedures. Using multiple, smaller procedures can also help reducing latency and increasing throughput, for queries that modify large volumes of data, such as large deletes. For example, multiple smaller single partition procedures are particularly useful to age out large stale data where strong global consistency is not required.
When creating a single-partitioned procedure, you can use PARAMETER clause to specify the partitioning parameter which is used to determine the target partition.
The PARAMETER should not be specified in the stored procedure used in this call since the stored procedure will be executed on every partition. If you only want to
execute the procedure in the partition as designated with PARAMETER, use callProcedure(ProcedureCallback, String, Object...) instead.
When creating a class stored procedure, the first argument in the procedure's run method must be the partition key, which matches the partition column type, followed by the
parameters as declared in the procedure. The argument partition key, not part of procedure's parameters, is assigned during the iteration of the partition set.
Example: A stored procedure with a parameter of long type and partition column of string type
CREATE TABLE tableWithStringPartition (id bigint NOT NULL,value_string varchar(50) NOT NULL,
value1 bigint NOT NULL,value2 bigint NOT NULL);
PARTITION TABLE tableWithStringPartition ON COLUMN value_string;
CREATE PROCEDURE FROM CLASS example.Everywhere;
PARTITION PROCEDURE Everywhere ON TABLE tableWithStringPartition COLUMN value_string;
public class Everywhere extends VoltProcedure {
public final SQLStmt stmt = new SQLStmt("SELECT count(*) FROM tableWithStringPartition where value1 > ?;");
public VoltTable[] run(String partitionKey, long value1) {
voltQueueSQL(stmt, value1);
return voltExecuteSQL(true);
}
}
The execution of the stored procedure may fail on one or more partitions. Thus check the status of the response on every partition.
callback - AllPartitionProcedureCallback that will be invoked with procedure results.procedureName - class name (not qualified by package) of the partitioned java procedure to execute.params - vararg list of procedure's parameter values.false if the procedures on all partition are not queued and true otherwise.NoConnectionsException - if this Client instance is not connected to any servers.java.io.IOException - if there is a Java network or connection problem.ProcCallException - on any VoltDB specific failure.