Class: Google::Cloud::Spanner::Client
- Inherits:
-
Object
- Object
- Google::Cloud::Spanner::Client
- Defined in:
- lib/google/cloud/spanner/client.rb
Overview
Instance Method Summary collapse
-
#close ⇒ Object
Closes the client connection and releases resources.
-
#commit(commit_options: nil, request_options: nil, call_options: nil) {|commit| ... } ⇒ Time, CommitResponse
Creates and commits a transaction for writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.
-
#commit_timestamp ⇒ ColumnValue
Creates a column value object representing setting a field's value to the timestamp of the commit.
-
#database ⇒ Database
The Spanner database connected to.
-
#database_id ⇒ String
The unique identifier for the database.
-
#database_role ⇒ String
The Spanner session creator role.
-
#delete(table, keys = [], commit_options: nil, request_options: nil, call_options: nil) ⇒ Time, CommitResponse
Deletes rows from a table.
-
#directed_read_options ⇒ Hash
A hash of values to specify the custom directed read options for executing SQL query.
-
#execute_partition_update(sql, params: nil, types: nil, query_options: nil, request_options: nil, call_options: nil) ⇒ Integer
(also: #execute_pdml)
Executes a Partitioned DML SQL statement.
-
#execute_query(sql, params: nil, types: nil, single_use: nil, query_options: nil, request_options: nil, call_options: nil, directed_read_options: nil) ⇒ Google::Cloud::Spanner::Results
(also: #execute, #query, #execute_sql)
Executes a SQL query.
-
#fields(types) ⇒ Fields
Creates a configuration object (Fields) that may be provided to queries or used to create STRUCT objects.
-
#insert(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Inserts new rows in a table.
-
#instance ⇒ Instance
The Spanner instance connected to.
-
#instance_id ⇒ String
The unique identifier for the instance.
-
#project ⇒ Project
The Spanner project connected to.
-
#project_id ⇒ String
The unique identifier for the project.
-
#query_options ⇒ Hash
A hash of values to specify the custom query options for executing SQL query.
-
#range(beginning, ending, exclude_begin: false, exclude_end: false) ⇒ Google::Cloud::Spanner::Range
Creates a Spanner Range.
-
#read(table, columns, keys: nil, index: nil, limit: nil, single_use: nil, request_options: nil, call_options: nil, directed_read_options: nil) ⇒ Google::Cloud::Spanner::Results
Read rows from a database table, as a simple alternative to #execute_query.
-
#replace(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Inserts or replaces rows in a table.
-
#reset ⇒ Object
Reset the client sessions.
-
#snapshot(strong: nil, timestamp: nil, read_timestamp: nil, staleness: nil, exact_staleness: nil, call_options: nil) {|snapshot| ... } ⇒ Object
Creates a snapshot read-only transaction for reads that execute atomically at a single logical point in time across columns, rows, and tables in a database.
-
#transaction(deadline: 120, commit_options: nil, request_options: nil, call_options: nil) {|transaction| ... } ⇒ Time, CommitResponse
Creates a transaction for reads and writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.
-
#update(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Updates existing rows in a table.
-
#upsert(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
(also: #save)
Inserts or updates rows in a table.
Instance Method Details
#close ⇒ Object
Closes the client connection and releases resources.
2154 2155 2156 |
# File 'lib/google/cloud/spanner/client.rb', line 2154 def close @pool.close end |
#commit(commit_options: nil, request_options: nil, call_options: nil) {|commit| ... } ⇒ Time, CommitResponse
Creates and commits a transaction for writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.
All changes are accumulated in memory until the block completes. Unlike #transaction, which can also perform reads, this operation accepts only mutations and makes a single API request.
Note: This method does not feature replay protection present in #transaction. This method makes a single RPC, whereas #transaction requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind changes.
1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 |
# File 'lib/google/cloud/spanner/client.rb', line 1666 def commit commit_options: nil, request_options: nil, call_options: nil, &block raise ArgumentError, "Must provide a block" unless block_given? = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| session.commit( commit_options: , request_options: , call_options: , &block ) end end |
#commit_timestamp ⇒ ColumnValue
Creates a column value object representing setting a field's value to the timestamp of the commit. (See Google::Cloud::Spanner::ColumnValue.commit_timestamp)
This placeholder value can only be used for timestamp columns that have set the option "(allow_commit_timestamp=true)" in the schema.
2147 2148 2149 |
# File 'lib/google/cloud/spanner/client.rb', line 2147 def ColumnValue. end |
#database ⇒ Database
The Spanner database connected to.
104 105 106 |
# File 'lib/google/cloud/spanner/client.rb', line 104 def database @project.database instance_id, database_id end |
#database_id ⇒ String
The unique identifier for the database.
86 87 88 |
# File 'lib/google/cloud/spanner/client.rb', line 86 def database_id @database_id end |
#database_role ⇒ String
The Spanner session creator role.
110 111 112 |
# File 'lib/google/cloud/spanner/client.rb', line 110 def database_role @database_role end |
#delete(table, keys = [], commit_options: nil, request_options: nil, call_options: nil) ⇒ Time, CommitResponse
Deletes rows from a table. Succeeds whether or not the specified rows were present.
Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.
Note: This method does not feature replay protection present in Transaction#delete (See #transaction). This method makes a single RPC, whereas Transaction#delete requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind deletions.
1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 |
# File 'lib/google/cloud/spanner/client.rb', line 1548 def delete table, keys = [], commit_options: nil, request_options: nil, call_options: nil = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| session.delete table, keys, commit_options: , request_options: , call_options: end end |
#directed_read_options ⇒ Hash
A hash of values to specify the custom directed read options for executing SQL query.
124 125 126 |
# File 'lib/google/cloud/spanner/client.rb', line 124 def @directed_read_options end |
#execute_partition_update(sql, params: nil, types: nil, query_options: nil, request_options: nil, call_options: nil) ⇒ Integer Also known as: execute_pdml
Executes a Partitioned DML SQL statement.
Partitioned DML is an alternate implementation with looser semantics to enable large-scale changes without running into transaction size limits or (accidentally) locking the entire table in one large transaction. At a high level, it partitions the keyspace and executes the statement on each partition in separate internal transactions.
Partitioned DML does not guarantee database-wide atomicity of the statement - it guarantees row-based atomicity, which includes updates to any indices. Additionally, it does not guarantee that it will execute exactly one time against each row - it guarantees "at least once" semantics.
Where DML statements must be executed using Transaction (see Transaction#execute_update), Partitioned DML statements are executed outside of a read/write transaction.
Not all DML statements can be executed in the Partitioned DML mode and the backend will return an error for the statements which are not supported.
DML statements must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table. InvalidArgumentError is raised if the statement does not qualify.
The method will block until the update is complete. Running a DML statement with this method does not offer exactly once semantics, and therefore the DML statement should be idempotent. The DML statement must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table. This is a Partitioned DML transaction in which a single Partitioned DML statement is executed. Partitioned DML partitions the and runs the DML statement over each partition in parallel using separate, internal transactions that commit independently. Partitioned DML transactions do not need to be committed.
Partitioned DML updates are used to execute a single DML statement with a different execution strategy that provides different, and often better, scalability properties for large, table-wide operations than DML in a Transaction#execute_update transaction. Smaller scoped statements, such as an OLTP workload, should prefer using Transaction#execute_update.
That said, Partitioned DML is not a drop-in replacement for standard DML used in Transaction#execute_update.
- The DML statement must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table.
- The statement is not applied atomically to all rows of the table. Rather, the statement is applied atomically to partitions of the table, in independent internal transactions. Secondary index rows are updated atomically with the base table rows.
- Partitioned DML does not guarantee exactly-once execution semantics
against a partition. The statement will be applied at least once to
each partition. It is strongly recommended that the DML statement
should be idempotent to avoid unexpected results. For instance, it
is potentially dangerous to run a statement such as
UPDATE table SET column = column + 1
as it could be run multiple times against some rows. - The partitions are committed automatically - there is no support for Commit or Rollback. If the call returns an error, or if the client issuing the DML statement dies, it is possible that some rows had the statement executed on them successfully. It is also possible that statement was never executed against other rows.
- If any error is encountered during the execution of the partitioned DML operation (for instance, a UNIQUE INDEX violation, division by zero, or a value that cannot be stored due to schema constraints), then the operation is stopped at that point and an error is returned. It is possible that at this point, some partitions have been committed (or even committed multiple times), and other partitions have not been run at all.
Given the above, Partitioned DML is good fit for large, database-wide, operations that are idempotent, such as deleting old rows from a very large table.
733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 |
# File 'lib/google/cloud/spanner/client.rb', line 733 def execute_partition_update sql, params: nil, types: nil, query_options: nil, request_options: nil, call_options: nil ensure_service! params, types = Convert.to_input_params_and_types params, types = Convert. , tag_type: :request_tag route_to_leader = LARHeaders.partition_query results = nil @pool.with_session do |session| results = session.execute_query \ sql, params: params, types: types, transaction: pdml_transaction(session), query_options: , request_options: , call_options: , route_to_leader: route_to_leader end # Stream all PartialResultSet to get ResultSetStats results.rows.to_a # Raise an error if there is not a row count returned if results.row_count.nil? raise Google::Cloud::InvalidArgumentError, "Partitioned DML statement is invalid." end results.row_count end |
#execute_query(sql, params: nil, types: nil, single_use: nil, query_options: nil, request_options: nil, call_options: nil, directed_read_options: nil) ⇒ Google::Cloud::Spanner::Results Also known as: execute, query, execute_sql
Executes a SQL query.
The following settings can be provided:
:exclude_replicas
(Hash) Exclude_replicas indicates what replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.:include_replicas
(Hash) Include_replicas indicates the order of replicas to process the request. If auto_failover_disabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 |
# File 'lib/google/cloud/spanner/client.rb', line 460 def execute_query sql, params: nil, types: nil, single_use: nil, query_options: nil, request_options: nil, call_options: nil, directed_read_options: nil validate_single_use_args! single_use ensure_service! params, types = Convert.to_input_params_and_types params, types = Convert. , tag_type: :request_tag single_use_tx = single_use_transaction single_use route_to_leader = LARHeaders.execute_query true results = nil @pool.with_session do |session| results = session.execute_query \ sql, params: params, types: types, transaction: single_use_tx, query_options: , request_options: , call_options: , directed_read_options: ( || @directed_read_options), route_to_leader: route_to_leader end results end |
#fields(types) ⇒ Fields
Creates a configuration object (Fields) that may be provided to queries or used to create STRUCT objects. (The STRUCT will be represented by the Data class.) See #execute and/or Fields#struct.
For more information, see Data Types - Constructing a STRUCT.
2059 2060 2061 |
# File 'lib/google/cloud/spanner/client.rb', line 2059 def fields types Fields.new types end |
#insert(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Inserts new rows in a table. If any of the rows already exist, the write or request fails with AlreadyExistsError.
Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.
Note: This method does not feature replay protection present in Transaction#insert (See #transaction). This method makes a single RPC, whereas Transaction#insert requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind inserts.
1208 1209 1210 1211 1212 1213 1214 1215 1216 |
# File 'lib/google/cloud/spanner/client.rb', line 1208 def insert table, rows, commit_options: nil, request_options: nil = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| session.insert table, rows, commit_options: , request_options: end end |
#instance ⇒ Instance
The Spanner instance connected to.
98 99 100 |
# File 'lib/google/cloud/spanner/client.rb', line 98 def instance @project.instance instance_id end |
#instance_id ⇒ String
The unique identifier for the instance.
80 81 82 |
# File 'lib/google/cloud/spanner/client.rb', line 80 def instance_id @instance_id end |
#project ⇒ Project
The Spanner project connected to.
92 93 94 |
# File 'lib/google/cloud/spanner/client.rb', line 92 def project @project end |
#project_id ⇒ String
The unique identifier for the project.
74 75 76 |
# File 'lib/google/cloud/spanner/client.rb', line 74 def project_id @project.service.project end |
#query_options ⇒ Hash
A hash of values to specify the custom query options for executing SQL query.
117 118 119 |
# File 'lib/google/cloud/spanner/client.rb', line 117 def @query_options end |
#range(beginning, ending, exclude_begin: false, exclude_end: false) ⇒ Google::Cloud::Spanner::Range
Creates a Spanner Range. This can be used in place of a Ruby Range when needing to exclude the beginning value.
2116 2117 2118 2119 2120 |
# File 'lib/google/cloud/spanner/client.rb', line 2116 def range beginning, ending, exclude_begin: false, exclude_end: false Range.new beginning, ending, exclude_begin: exclude_begin, exclude_end: exclude_end end |
#read(table, columns, keys: nil, index: nil, limit: nil, single_use: nil, request_options: nil, call_options: nil, directed_read_options: nil) ⇒ Google::Cloud::Spanner::Results
Read rows from a database table, as a simple alternative to #execute_query.
The following settings can be provided:
:exclude_replicas
(Hash) Exclude_replicas indicates what replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.:include_replicas
(Hash) Include_replicas indicates the order of replicas to process the request. If auto_failover_disabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.
953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 |
# File 'lib/google/cloud/spanner/client.rb', line 953 def read table, columns, keys: nil, index: nil, limit: nil, single_use: nil, request_options: nil, call_options: nil, directed_read_options: nil validate_single_use_args! single_use ensure_service! columns = Array(columns).map(&:to_s) keys = Convert.to_key_set keys single_use_tx = single_use_transaction single_use route_to_leader = LARHeaders.read false = Convert. , tag_type: :request_tag results = nil @pool.with_session do |session| results = session.read \ table, columns, keys: keys, index: index, limit: limit, transaction: single_use_tx, request_options: , call_options: , directed_read_options: ( || @directed_read_options), route_to_leader: route_to_leader end results end |
#replace(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Inserts or replaces rows in a table. If any of the rows already exist,
it is deleted, and the column values provided are inserted instead.
Unlike #upsert, this means any values not explicitly written become
NULL
.
Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.
Note: This method does not feature replay protection present in Transaction#replace (See #transaction). This method makes a single RPC, whereas Transaction#replace requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind replaces.
1444 1445 1446 1447 1448 1449 |
# File 'lib/google/cloud/spanner/client.rb', line 1444 def replace table, rows, commit_options: nil, request_options: nil @pool.with_session do |session| session.replace table, rows, commit_options: , request_options: end end |
#reset ⇒ Object
Reset the client sessions.
2161 2162 2163 |
# File 'lib/google/cloud/spanner/client.rb', line 2161 def reset @pool.reset end |
#snapshot(strong: nil, timestamp: nil, read_timestamp: nil, staleness: nil, exact_staleness: nil, call_options: nil) {|snapshot| ... } ⇒ Object
Creates a snapshot read-only transaction for reads that execute atomically at a single logical point in time across columns, rows, and tables in a database. For transactions that only read, snapshot read-only transactions provide simpler semantics and are almost always faster than read-write transactions.
1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 |
# File 'lib/google/cloud/spanner/client.rb', line 1963 def snapshot strong: nil, timestamp: nil, read_timestamp: nil, staleness: nil, exact_staleness: nil, call_options: nil validate_snapshot_args! strong: strong, timestamp: , read_timestamp: , staleness: staleness, exact_staleness: exact_staleness ensure_service! unless Thread.current[IS_TRANSACTION_RUNNING_KEY].nil? raise "Nested snapshots are not allowed" end @pool.with_session do |session| snp_grpc = @project.service.create_snapshot \ session.path, strong: strong, timestamp: ( || ), staleness: (staleness || exact_staleness), call_options: Thread.current[IS_TRANSACTION_RUNNING_KEY] = true snp = Snapshot.from_grpc snp_grpc, session, @directed_read_options yield snp if block_given? ensure Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil end nil end |
#transaction(deadline: 120, commit_options: nil, request_options: nil, call_options: nil) {|transaction| ... } ⇒ Time, CommitResponse
Creates a transaction for reads and writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.
The transaction will always commit unless an error is raised. If the error raised is Rollback the transaction method will return without passing on the error. All other errors will be passed on.
All changes are accumulated in memory until the block completes.
Transactions will be automatically retried when possible, until
deadline
is reached. This operation makes separate API requests to
begin and commit the transaction.
1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 |
# File 'lib/google/cloud/spanner/client.rb', line 1837 def transaction deadline: 120, commit_options: nil, request_options: nil, call_options: nil ensure_service! unless Thread.current[IS_TRANSACTION_RUNNING_KEY].nil? raise "Nested transactions are not allowed" end deadline = validate_deadline deadline backoff = 1.0 start_time = current_time = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| tx = session.create_empty_transaction if tx.transaction_tag = [:transaction_tag] end begin Thread.current[IS_TRANSACTION_RUNNING_KEY] = true yield tx transaction_id = nil transaction_id = tx.transaction_id if tx.existing_transaction? commit_resp = @project.service.commit \ tx.session.path, tx.mutations, transaction_id: transaction_id, commit_options: , request_options: , call_options: resp = CommitResponse.from_grpc commit_resp ? resp : resp. rescue GRPC::Aborted, Google::Cloud::AbortedError, GRPC::Internal, Google::Cloud::InternalError => e check_and_propagate_err! e, (current_time - start_time > deadline) # Sleep the amount from RetryDelay, or incremental backoff sleep(delay_from_aborted(e) || backoff *= 1.3) # Create new transaction on the session and retry the block tx = session.create_transaction retry rescue StandardError => e # Rollback transaction when handling unexpected error tx.session.rollback tx.transaction_id if tx.existing_transaction? # Return nil if raised with rollback. return nil if e.is_a? Rollback # Re-raise error. raise e ensure Thread.current[IS_TRANSACTION_RUNNING_KEY] = nil end end end |
#update(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse
Updates existing rows in a table. If any of the rows does not already exist, the request fails with NotFoundError.
Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.
Note: This method does not feature replay protection present in Transaction#update (See #transaction). This method makes a single RPC, whereas Transaction#update requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind updates.
1325 1326 1327 1328 1329 1330 1331 1332 1333 |
# File 'lib/google/cloud/spanner/client.rb', line 1325 def update table, rows, commit_options: nil, request_options: nil = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| session.update table, rows, commit_options: , request_options: end end |
#upsert(table, rows, commit_options: nil, request_options: nil) ⇒ Time, CommitResponse Also known as: save
Inserts or updates rows in a table. If any of the rows already exist, then its column values are overwritten with the ones provided. Any column values not explicitly written are preserved.
Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.
Note: This method does not feature replay protection present in Transaction#upsert (See #transaction). This method makes a single RPC, whereas Transaction#upsert requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind upserts.
1089 1090 1091 1092 1093 1094 1095 1096 1097 |
# File 'lib/google/cloud/spanner/client.rb', line 1089 def upsert table, rows, commit_options: nil, request_options: nil = Convert. \ , tag_type: :transaction_tag @pool.with_session do |session| session.upsert table, rows, commit_options: , request_options: end end |