Google.Cloud.Spanner.Data - Class SpannerDataReader (5.0.0-beta02)

public sealed class SpannerDataReader : DbDataReader, IEnumerable, IDataReader, IDataRecord, IDisposable, IAsyncDisposable

Reference documentation and code samples for the Google.Cloud.Spanner.Data class SpannerDataReader.

Reads a forward-only stream of rows from a data source.

Inheritance

object > MarshalByRefObject > DbDataReader > SpannerDataReader

Implements

IEnumerable, IDataReader, IDataRecord, IDisposable, IAsyncDisposable

Inherited Members

DbDataReader.CloseAsync()

DbDataReader.DisposeAsync()

DbDataReader.GetFieldValueAsync<T>(int)

DbDataReader.GetFieldValueAsync<T>(int, CancellationToken)

DbDataReader.GetStream(int)

DbDataReader.GetTextReader(int)

DbDataReader.IsDBNullAsync(int)

DbDataReader.IsDBNullAsync(int, CancellationToken)

DbDataReader.NextResultAsync()

DbDataReader.NextResultAsync(CancellationToken)

DbDataReader.ReadAsync()

DbDataReader.VisibleFieldCount

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

object.GetHashCode()

object.GetType()

object.ToString()

Namespace

Google.Cloud.Spanner.Data

Assembly

Google.Cloud.Spanner.Data.dll

Properties

Depth

public override int Depth { get; }

Gets a value indicating the depth of nesting for the current row.

Property Value
Type	Description
`int`	The depth of nesting for the current row.

Overrides

DbDataReader.Depth

FieldCount

public override int FieldCount { get; }

Gets the number of columns in the current row.

Property Value
Type	Description
`int`	The number of columns in the current row.

Overrides

DbDataReader.FieldCount

Exceptions
Type	Description
`NotSupportedException`	There is no current connection to an instance of SQL Server.

HasRows

public override bool HasRows { get; }

Gets a value that indicates whether the SpannerDataReader contains one or more rows. If any rows have been read, this will continue to return true even when there are no more rows.

Property Value
Type	Description
`bool`

Overrides

DbDataReader.HasRows

IsClosed

public override bool IsClosed { get; }

Gets a value indicating whether the DbDataReader is closed.

Property Value
Type	Description
`bool`	true if the DbDataReader is closed; otherwise, false.

Overrides

DbDataReader.IsClosed

Exceptions
Type	Description
`InvalidOperationException`	The DbDataReader is closed.

this[int]

public override object this[int i] { get; }

Gets the value of the specified column as an instance of object.

Parameter
Name	Description
`i`	`int`

Property Value
Type	Description
`object`	The value of the specified column.

Overrides

DbDataReader.this[int]

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.

this[string]

public override object this[string name] { get; }

Gets the value of the specified column as an instance of object.

Parameter
Name	Description
`name`	`string` The name of the column.

Property Value
Type	Description
`object`	The value of the specified column.

Overrides

DbDataReader.this[string]

Exceptions
Type	Description
`IndexOutOfRangeException`	No column with the specified name was found.

RecordsAffected

public override int RecordsAffected { get; }

Gets the number of rows changed, inserted, or deleted by execution of the SQL statement.

Property Value
Type	Description
`int`	The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected or the statement failed.

Overrides

DbDataReader.RecordsAffected

Methods

Close()

public override void Close()

Closes the DbDataReader object.

Overrides

DbDataReader.Close()

Dispose(bool)

protected override void Dispose(bool disposing)

Releases the managed resources used by the DbDataReader and optionally releases the unmanaged resources.

Parameter
Name	Description
`disposing`	`bool` true to release managed and unmanaged resources; false to release only unmanaged resources.

Overrides

DbDataReader.Dispose(bool)

GetBoolean(int)

public override bool GetBoolean(int i)

Gets the value of the specified column as a Boolean.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`bool`	The value of the specified column.

Overrides

DbDataReader.GetBoolean(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetByte(int)

public override byte GetByte(int i)

Gets the value of the specified column as a byte.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`byte`	The value of the specified column.

Overrides

DbDataReader.GetByte(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetBytes(int, long, byte[], int, int)

public override long GetBytes(int ordinal, long fieldOffset, byte[] buffer, int bufferOffset, int length)

Reads a specified number of bytes from the specified column starting at a specified index and writes them to a buffer starting at a specified position in the buffer.

Parameters
Name	Description
`ordinal`	`int` The zero-based column ordinal.
`fieldOffset`	`long`
`buffer`	`byte` The buffer into which to copy the data.
`bufferOffset`	`int` The index with the buffer to which the data will be copied.
`length`	`int` The maximum number of characters to read.

Returns
Type	Description
`long`	The actual number of bytes read.

Overrides

DbDataReader.GetBytes(int, long, byte[], int, int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetChar(int)

public override char GetChar(int i)

Gets the value of the specified column as a single character.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`char`	The value of the specified column.

Overrides

DbDataReader.GetChar(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetChars(int, long, char[], int, int)

public override long GetChars(int i, long fieldoffset, char[] buffer, int bufferoffset, int length)

Reads a specified number of characters from a specified column starting at a specified index, and writes them to a buffer starting at a specified position.

Parameters
Name	Description
`i`	`int`
`fieldoffset`	`long`
`buffer`	`char` The buffer into which to copy the data.
`bufferoffset`	`int`
`length`	`int` The maximum number of characters to read.

Returns
Type	Description
`long`	The actual number of characters read.

Overrides

DbDataReader.GetChars(int, long, char[], int, int)

GetDataTypeName(int)

public override string GetDataTypeName(int i)

Gets name of the data type of the specified column.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`string`	The name of the data type.

Overrides

DbDataReader.GetDataTypeName(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.

GetDateTime(int)

public override DateTime GetDateTime(int i)

Gets the value of the specified column as a DateTime object.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`DateTime`	The value of the specified column.

Overrides

DbDataReader.GetDateTime(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetDecimal(int)

public override decimal GetDecimal(int i)

Gets the value of the specified column as a decimal.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`decimal`	The value of the specified column.

Overrides

DbDataReader.GetDecimal(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetDouble(int)

public override double GetDouble(int i)

Gets the value of the specified column as a double-precision floating point number.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`double`	The value of the specified column.

Overrides

DbDataReader.GetDouble(int)

Exceptions
Type	Description
`InvalidCastException`	The specified cast is not valid.

GetEnumerator()

public override IEnumerator GetEnumerator()

Returns an IEnumerator that can be used to iterate through the rows in the data reader.

Returns
Type	Description
`IEnumerator`	An IEnumerator that can be used to iterate through the rows in the data reader.

Overrides

DbDataReader.GetEnumerator()

GetFieldType(int)

public override Type GetFieldType(int i)

Gets the data type of the specified column.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`Type`	The data type of the specified column.

Overrides

DbDataReader.GetFieldType(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetFieldValue<T>(int)

public override T GetFieldValue<T>(int ordinal)

Gets the value of the specified column as the requested type.

Parameter
Name	Description
`ordinal`	`int` The zero-based column ordinal.

Returns
Type	Description
`T`	The value of the specified column.

Type Parameter
Name	Description
`T`	The type of the value to be returned.

Overrides

DbDataReader.GetFieldValue<T>(int)

Exceptions
Type	Description
`InvalidOperationException`	The connection was dropped or closed during data retrieval. -or- The data reader was closed during data retrieval. -or- There is no data ready to be read (for example, the first Read() hasn't been called, or it returned false). -or- The reader tried to read a previously-read column in sequential mode. -or- There was an asynchronous operation in progress. This applies to all Get* methods when running in sequential mode, as they could be called while reading a stream.
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The value returned by the database doesn't match or cannot be cast to T.

GetFieldValue<T>(string)

public T GetFieldValue<T>(string columnName)

Gets the value of the specified column as type T.

Parameter
Name	Description
`columnName`	`string` The name of the column whose value will be returned. Must not be null.

Returns
Type	Description
`T`	The value of the column at the current row, converted to type T.

Type Parameter

Name Description

T

The expected return type. If possible the return type will be converted to this type. If conversion is requested between incompatible types, an InvalidOperationException will be thrown. If the conversion fails due to the contents returned (for example a string representing a boolean does not have either 'true' or 'false') then a FormatException exception will be thrown as documented by the Convert class.

GetFloat(int)

public override float GetFloat(int i)

Gets the value of the specified column as a single-precision floating point number.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`float`	The value of the specified column.

Overrides

DbDataReader.GetFloat(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetGuid(int)

public override Guid GetGuid(int i)

Gets the value of the specified column as a globally unique identifier (GUID).

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`Guid`	The value of the specified column.

Overrides

DbDataReader.GetGuid(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetInt16(int)

public override short GetInt16(int i)

Gets the value of the specified column as a 16-bit signed integer.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`short`	The value of the specified column.

Overrides

DbDataReader.GetInt16(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetInt32(int)

public override int GetInt32(int i)

Gets the value of the specified column as a 32-bit signed integer.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`int`	The value of the specified column.

Overrides

DbDataReader.GetInt32(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetInt64(int)

public override long GetInt64(int i)

Gets the value of the specified column as a 64-bit signed integer.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`long`	The value of the specified column.

Overrides

DbDataReader.GetInt64(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetJsonValue(int)

public Value GetJsonValue(int i)

Gets the value of the specified column as a pure Protobuf type.

Parameter
Name	Description
`i`	`int` The index of the column whose value will be returned.

Returns
Type	Description
`Value`	The raw protobuf as a Value.

Exceptions
Type	Description
`InvalidOperationException`	The reader is not currently positioned on a valid row.

GetName(int)

public override string GetName(int i)

Gets the name of the column, given the zero-based column ordinal.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`string`	The name of the specified column.

Overrides

DbDataReader.GetName(int)

GetNumeric(int)

public SpannerNumeric GetNumeric(int i)

Gets the value of the specified column as type Google.Cloud.Spanner.V1.SpannerNumeric.

Parameter
Name	Description
`i`	`int` The index of the column to retrieve.

Returns
Type	Description
`Google.Cloud.Spanner.V1.SpannerNumeric`	The value converted to a Google.Cloud.Spanner.V1.SpannerNumeric.

GetOrdinal(string)

public override int GetOrdinal(string name)

Gets the column ordinal given the name of the column.

Parameter
Name	Description
`name`	`string` The name of the column.

Returns
Type	Description
`int`	The zero-based column ordinal.

Overrides

DbDataReader.GetOrdinal(string)

Exceptions
Type	Description
`IndexOutOfRangeException`	The name specified is not a valid column name.

GetOrdinalAsync(string, CancellationToken)

public Task<int> GetOrdinalAsync(string name, CancellationToken cancellationToken = default)

Returns the column ordinal given the name of the column, asynchronously requesting metadata from the database if necessary.

Parameters
Name	Description
`name`	`string` The name of the column.
`cancellationToken`	`CancellationToken` A cancellation token to cancel reading metadata. Defaults to None.

Returns
Type	Description
`Taskint`	The zero-based column ordinal.

GetPgNumeric(int)

public PgNumeric GetPgNumeric(int i)

Gets the value of the specified column as type Google.Cloud.Spanner.V1.PgNumeric.

Parameter
Name	Description
`i`	`int` The index of the column to retrieve.

Returns
Type	Description
`Google.Cloud.Spanner.V1.PgNumeric`	The value converted to a Google.Cloud.Spanner.V1.PgNumeric.

GetReadTimestamp()

public Timestamp GetReadTimestamp()

Gets the read timestamp if ReturnReadTimestamp was true else returns null.

Returns
Type	Description
`Timestamp`	The value converted to a Timestamp, or `null` if ReturnReadTimestamp was false.

Remarks

The read timestamp can be read before Read() or ReadAsync(CancellationToken) is called.

GetReadTimestampAsync(CancellationToken)

public Task<Timestamp> GetReadTimestampAsync(CancellationToken cancellationToken)

Gets the read timestamp if ReturnReadTimestamp was true else returns null.

Parameter
Name	Description
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`TaskTimestamp`	The value converted to a Timestamp, or `null` if ReturnReadTimestamp was false.

GetSchemaTable()

public override DataTable GetSchemaTable()

When enabled, returns the schema of the query as a DataTable. This feature needs to be enabled in the connection string via the EnableGetSchemaTable property.

Returns
Type	Description
`DataTable`	A `DataTable` with schema information about the query, or `null` if the feature is not enabled in the connection string.

Overrides

DbDataReader.GetSchemaTable()

Remarks

DbDataAdapter will use this method automatically, but there is not enough information available for it to do so to reliably manage data sets. This method returns null by default to avoid this causing problems.

When the EnableGetSchemaTable property in the connection string is set to true, a DataTable is returned with the following columns populated:

ColumnName (String): The name of the column
ColumnOrdinal (Int32): The ordinal value of the column
DataType (Type): The default CLR type of the column
ProviderType (SpannerDbType): The Spanner-specific data type of the column

The following additional columns are present in the table, but not currently populated:

ColumnSize
NumericPrecision
NumericScale

Future releases may expand the set of columns, or populate more of the existing columns.

GetSpannerDate(int)

public SpannerDate GetSpannerDate(int i)

Gets the value of the specified column as type Google.Cloud.Spanner.V1.SpannerDate.

Parameter
Name	Description
`i`	`int` The index of the column to retrieve.

Returns
Type	Description
`Google.Cloud.Spanner.V1.SpannerDate`	The value converted to a Google.Cloud.Spanner.V1.SpannerDate.

GetString(int)

public override string GetString(int i)

Gets the value of the specified column as an instance of string.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`string`	The value of the specified column.

Overrides

DbDataReader.GetString(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.
`InvalidCastException`	The specified cast is not valid.

GetTimestamp(int)

public Timestamp GetTimestamp(int i)

Gets the value of the specified column as type Timestamp.

Parameter
Name	Description
`i`	`int` The index of the column to retrieve.

Returns
Type	Description
`Timestamp`	The value converted to a Timestamp.

GetValue(int)

public override object GetValue(int i)

Gets the value of the specified column as an instance of object.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`object`	The value of the specified column.

Overrides

DbDataReader.GetValue(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.

GetValues(object[])

public override int GetValues(object[] values)

Populates an array of objects with the column values of the current row.

Parameter
Name	Description
`values`	`object` An array of object into which to copy the attribute columns.

Returns
Type	Description
`int`	The number of instances of object in the array.

Overrides

DbDataReader.GetValues(object[])

IsDBNull(int)

public override bool IsDBNull(int i)

Gets a value that indicates whether the column contains nonexistent or missing values.

Parameter
Name	Description
`i`	`int`

Returns
Type	Description
`bool`	true if the specified column is equivalent to DBNull; otherwise, false.

Overrides

DbDataReader.IsDBNull(int)

Exceptions
Type	Description
`IndexOutOfRangeException`	The column index is out of range.

NextResult()

public override bool NextResult()

Advances the reader to the next result when reading the results of a batch of statements.

Returns
Type	Description
`bool`	true if there are more result sets; otherwise, false.

Overrides

DbDataReader.NextResult()

Read()

public override bool Read()

Advances the reader to the next record in a result set.

Returns
Type	Description
`bool`	true if there are more rows; otherwise, false.

Overrides

DbDataReader.Read()

ReadAsync(CancellationToken)

public override Task<bool> ReadAsync(CancellationToken cancellationToken)

Reads the next row of values from Cloud Spanner. Important: Cloud Spanner supports limited cancellation of this task.

Parameter
Name	Description
`cancellationToken`	`CancellationToken` A cancellation token to cancel the read. Cloud Spanner currently supports limited cancellation while advancing the read to the next row.

Returns
Type	Description
`Taskbool`	True if another row was read.

Overrides

DbDataReader.ReadAsync(CancellationToken)