Create a BigQuery read session

Create a new read session to specify the BigQuery table to read from, the columns to project, and an optional row filter.

Code sample

Java

Before trying this sample, follow the Java setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Java API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.bigquery.storage.v1.BigQueryReadClient;
import com.google.cloud.bigquery.storage.v1.CreateReadSessionRequest;
import com.google.cloud.bigquery.storage.v1.DataFormat;
import com.google.cloud.bigquery.storage.v1.ProjectName;
import com.google.cloud.bigquery.storage.v1.ReadSession;
import com.google.cloud.bigquery.storage.v1.ReadSession.TableReadOptions;
import com.google.cloud.bigquery.storage.v1.TableName;
import java.io.IOException;

public class CreateReadSession {

  /**
   * Creates a BigQuery Storage read session for a specified table, projecting selected columns and
   * applying an optional row filter.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param datasetId The BigQuery dataset ID containing the table (for example,
   *     "example_dataset").
   * @param tableId The BigQuery table ID to read from (for example, "example_table").
   */
  public static void createReadSession(String projectId, String datasetId, String tableId) {
    ProjectName parent = ProjectName.of(projectId);
    TableName table = TableName.of(projectId, datasetId, tableId);

    // If no fields are specified, all fields will be returned.
    TableReadOptions readOptions =
        TableReadOptions.newBuilder()
            .addSelectedFields("field_01")
            .addSelectedFields("field_02")
            .setRowRestriction("field_03 > 100")
            .build();

    ReadSession readSession =
        ReadSession.newBuilder()
            .setTable(table.toString())
            .setDataFormat(DataFormat.ARROW)
            .setReadOptions(readOptions)
            .build();

    CreateReadSessionRequest request =
        CreateReadSessionRequest.newBuilder()
            .setParent(parent.toString())
            .setReadSession(readSession)
            .setMaxStreamCount(1)
            .build();

    try (BigQueryReadClient client = BigQueryReadClient.create()) {
      ReadSession session = client.createReadSession(request);
      System.out.printf("Successfully created read session: %s%n", session.getName());
      if (session.getStreamsCount() > 0) {
        System.out.printf("Stream found: %s%n", session.getStreams(0).getName());
      } else {
        System.out.println("No streams found in the session.");
      }
    } catch (NotFoundException err) {
      System.err.printf(
          "error: table '%s' not found: %s%n", table, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create read session for table '%s': %s%n", table, err.getMessage());
    }
  }

Node.js

Before trying this sample, follow the Node.js setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Node.js API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

const {BigQueryReadClient} = require('@google-cloud/bigquery-storage');
const {status} = require('@grpc/grpc-js');

const client = new BigQueryReadClient();

/**
 * Creates a read session for a BigQuery table.
 *
 * @param {string} projectId The project ID to use for billing and quota (e.g., 'my-project-id').
 * @param {string} datasetId The ID of the dataset to read from (e.g., 'my_dataset').
 * @param {string} tableId The ID of the table to read from (e.g., 'my_table').
 */
async function createReadSession(
  projectId, datasetId, tableId
) {
  const parent = `projects/${projectId}`;
  const table = `projects/${projectId}/datasets/${datasetId}/tables/${tableId}`;

  const readOptions = {
    selectedFields: ['field_01', 'field_02'],
    rowRestriction: 'field_03 > 100',
  };

  const request = {
    parent,
    readSession: {
      table,
      dataFormat: 'AVRO',
      readOptions,
    },
    maxStreamCount: 1,
  };

  try {
    const [session] = await client.createReadSession(request);

    console.log(`Read session created: ${session.name}`);
    console.log('Session details:');
    console.log(`  Table: ${session.table}`);
    console.log(`  Data format: ${session.dataFormat}`);
    console.log(`  Estimated row count: ${session.estimatedRowCount}`);

    if (session.streams.length > 0) {
      const streamName = session.streams[0].name;
      console.log(`  First stream: ${streamName}`);
    } else {
      console.log('  No streams found in the session.');
    }

    if (session.avroSchema && session.avroSchema.schema) {
      console.log('  AVRO schema:');
      console.log(`  ${session.avroSchema.schema}`);
    }
  } catch (err) {
    if (err.code === status.NOT_FOUND) {
      console.log(
        `Could not find table ${table}. Please ensure the table exists and you have permission to read it.`,
      );
    } else {
      console.error('Error creating read session:', err);
    }
  }
}

Python

Before trying this sample, follow the Python setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Python API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

from google.api_core.exceptions import NotFound
from google.cloud.bigquery_storage_v1 import BigQueryReadClient
from google.cloud.bigquery_storage_v1.types import DataFormat, ReadSession

client = BigQueryReadClient()


def create_read_session(
    project_id: str,
    dataset_id: str,
    table_id: str,
) -> None:
    """Creates a read session for a BigQuery table.

    Args:
        project_id: The project ID that will be billed for the read session.
        dataset_id: The dataset ID of the table to read from.
        table_id: The table ID of the table to read from.
    """

    parent = f"projects/{project_id}"
    table = client.table_path(project_id, dataset_id, table_id)

    # If no fields are specified, all fields will be returned.
    read_options = ReadSession.TableReadOptions(
        selected_fields=["field_01", "field_02"], row_restriction="field_03 > 100"
    )

    read_session = ReadSession(
        table=table,
        data_format=DataFormat.ARROW,
        read_options=read_options,
    )

    try:
        session = client.create_read_session(
            parent=parent,
            read_session=read_session,
            max_stream_count=1,
        )

        print(f"Successfully created read session: {session.name}")
        if session.streams:
            print(f"Stream found: {session.streams[0].name}")
        else:
            print("No streams found in the session.")

    except NotFound:
        print(
            f"Could not find the table '{table}'. Please check that the table exists."
        )

What's next

To search and filter code samples for other Google Cloud products, see the Google Cloud sample browser.