All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.cloud.spanner.ReadContext Maven / Gradle / Ivy

There is a newer version: 6.81.1
Show newest version
/*
 * Copyright 2017 Google LLC
 *
 * Licensed 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 com.google.cloud.spanner;

import com.google.api.core.ApiFuture;
import com.google.cloud.spanner.Options.QueryOption;
import com.google.cloud.spanner.Options.ReadOption;
import javax.annotation.Nullable;

/**
 * A concurrency context in which to run a read or SQL statement. All {@code ReadContext}s are
 * implicitly bound to a {@link Session} and therefore a particular {@link Database}.
 */
public interface ReadContext extends AutoCloseable {
  /**
   * Used to specify the mode in which the query should be analyzed by {@link
   * ReadContext#analyzeQuery(Statement,QueryAnalyzeMode)}.
   */
  enum QueryAnalyzeMode {
    /** Retrieves only the query plan information. No result data is returned. */
    PLAN,
    /** Retrieves both query plan and query execution statistics along with the result data. */
    PROFILE
  }
  /**
   * Reads zero or more rows from a database.
   *
   * 

Implementations may or may not block in the initial {@code read(...)} call; for those that * do not, the remote call will be initiated immediately but blocking on the response is deferred * to the first {@link ResultSet#next()} call. Regardless of blocking behavior, any {@link * SpannerException} is deferred to the first or subsequent {@link ResultSet#next()} call. * * *

{@code
   * ReadContext readContext = dbClient.singleUse();
   * ResultSet resultSet =
   *     readContext.read(
   *         "Albums",
   *         // KeySet.all() can be used to read all rows in a table. KeySet exposes other
   *         // methods to read only a subset of the table.
   *         KeySet.all(),
   *         Arrays.asList("SingerId", "AlbumId", "AlbumTitle"));
   * }
* * * * @param table the name of the table to read * @param keys the keys and ranges of rows to read. Regardless of ordering in {@code keys}, rows * are returned in their natural key order. * @param columns the columns to read * @param options the options to configure the read */ ResultSet read(String table, KeySet keys, Iterable columns, ReadOption... options); /** * Same as {@link #read(String, KeySet, Iterable, ReadOption...)}, but is guaranteed to be * non-blocking and will return the results as an {@link AsyncResultSet}. */ AsyncResultSet readAsync( String table, KeySet keys, Iterable columns, ReadOption... options); /** * Reads zero or more rows from a database using an index. * *

Implementations may or may not block in the initial {@code read(...)} call; for those that * do not, the remote call will be initiated immediately but blocking on the response is deferred * to the first {@link ResultSet#next()} call. Regardless of blocking behavior, any {@link * SpannerException} is deferred to the first or subsequent {@link ResultSet#next()} call. * * *

{@code
   * ReadContext readContext = dbClient.singleUse();
   * Struct row =
   *     readContext.readRowUsingIndex("Albums", "AlbumsByAlbumId", Key.of(1, "Green"),
   *         Arrays.asList("AlbumId", "AlbumTitle"));
   * }
* * * * @param table the name of the table to read * @param index the name of the index on {@code table} to use * @param keys the keys and ranges of index rows to read. Regardless of ordering in {@code keys}, * rows are returned in the natural key order of the index. * @param columns the columns to read * @param options the options to configure the read */ ResultSet readUsingIndex( String table, String index, KeySet keys, Iterable columns, ReadOption... options); /** * Same as {@link #readUsingIndex(String, String, KeySet, Iterable, ReadOption...)}, but is * guaranteed to be non-blocking and will return its results as an {@link AsyncResultSet}. */ AsyncResultSet readUsingIndexAsync( String table, String index, KeySet keys, Iterable columns, ReadOption... options); /** * Reads a single row from a database, returning {@code null} if the row does not exist. * * *
{@code
   * ReadContext readContext = dbClient.singleUse();
   * Struct row =
   *     readContext.readRow("Albums", Key.of(2, 1), Arrays.asList("MarketingBudget"));
   * }
* * * * @param table the name of the table to read * @param key the row to read * @param columns the columns to return */ @Nullable Struct readRow(String table, Key key, Iterable columns); /** Same as {@link #readRow(String, Key, Iterable)}, but is guaranteed to be non-blocking. */ ApiFuture readRowAsync(String table, Key key, Iterable columns); /** * Reads a single row from a database using an index, returning {@code null} if the row does not * exist. * * *
{@code
   * ReadContext readContext = dbClient.singleUse();
   * Struct row =
   *     readContext.readRowUsingIndex("Albums", "AlbumsByAlbumId", Key.of(1, "Green"),
   *         Arrays.asList("AlbumId", "AlbumTitle"));
   * }
* * * * @param table the name of the table to read * @param index the name of the index on {@code table} to use * @param key the index row to read * @param columns the columns to return */ @Nullable Struct readRowUsingIndex(String table, String index, Key key, Iterable columns); /** * Same as {@link #readRowUsingIndex(String, String, Key, Iterable)}, but is guaranteed to be * non-blocking. */ ApiFuture readRowUsingIndexAsync( String table, String index, Key key, Iterable columns); /** * Executes a query against the database. Can also execute a DML statement with returning clause * in a read/write transaction. * *

Implementations may or may not block in the initial {@code executeQuery(...)} call; for * those that do not, the remote call will be initiated immediately but blocking on the response * is deferred to the first {@link ResultSet#next()} call. Regardless of blocking behavior, any * {@link SpannerException} is deferred to the first or subsequent {@link ResultSet#next()} call. * * *

{@code
   * // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
   * // null.
   * ReadContext readContext = dbClient.singleUse();
   * ResultSet resultSet =
   *     readContext.executeQuery(
   *         Statement.of(
   *             "SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime FROM Albums"));
   * }
* * * * @param statement the query statement to execute * @param options the options to configure the query */ ResultSet executeQuery(Statement statement, QueryOption... options); /** * Same as {@link #executeQuery(Statement, QueryOption...)}, but is guaranteed to be non-blocking * and returns its results as an {@link AsyncResultSet}. */ AsyncResultSet executeQueryAsync(Statement statement, QueryOption... options); /** * Analyzes a query and returns query plan and/or query execution statistics information. * *

The query plan and query statistics information is contained in {@link * com.google.spanner.v1.ResultSetStats} that can be accessed by calling {@link * ResultSet#getStats()} on the returned {@code ResultSet}. * * *

{@code
   * ReadContext rc = dbClient.singleUse();
   * ResultSet resultSet =
   *     rc.analyzeQuery(
   *         Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"),
   *         ReadContext.QueryAnalyzeMode.PROFILE);
   * while (resultSet.next()) {
   *   // Discard the results. We're only processing because getStats() below requires it.
   *   resultSet.getCurrentRowAsStruct();
   * }
   * ResultSetStats stats = resultSet.getStats();
   * }
* * * * @param statement the query statement to execute * @param queryMode the mode in which to execute the query */ ResultSet analyzeQuery(Statement statement, QueryAnalyzeMode queryMode); /** Closes this read context and frees up the underlying resources. */ @Override void close(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy