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

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
TypeDescription
int

The depth of nesting for the current row.

Overrides

FieldCount

public override int FieldCount { get; }

Gets the number of columns in the current row.

Property Value
TypeDescription
int

The number of columns in the current row.

Overrides
Exceptions
TypeDescription
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
TypeDescription
bool
Overrides

IsClosed

public override bool IsClosed { get; }

Gets a value indicating whether the DbDataReader is closed.

Property Value
TypeDescription
bool

true if the DbDataReader is closed; otherwise, false.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Property Value
TypeDescription
object

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
namestring

The name of the column.

Property Value
TypeDescription
object

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
TypeDescription
int

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

Overrides

Methods

Close()

public override void Close()

Closes the DbDataReader object.

Overrides

Dispose(bool)

protected override void Dispose(bool disposing)

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

Parameter
NameDescription
disposingbool

true to release managed and unmanaged resources; false to release only unmanaged resources.

Overrides

GetBoolean(int)

public override bool GetBoolean(int i)

Gets the value of the specified column as a Boolean.

Parameter
NameDescription
iint
Returns
TypeDescription
bool

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
byte

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
ordinalint

The zero-based column ordinal.

fieldOffsetlong
bufferbyte

The buffer into which to copy the data.

bufferOffsetint

The index with the buffer to which the data will be copied.

lengthint

The maximum number of characters to read.

Returns
TypeDescription
long

The actual number of bytes read.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
char

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
fieldoffsetlong
bufferchar

The buffer into which to copy the data.

bufferoffsetint
lengthint

The maximum number of characters to read.

Returns
TypeDescription
long

The actual number of characters read.

Overrides

GetDataTypeName(int)

public override string GetDataTypeName(int i)

Gets name of the data type of the specified column.

Parameter
NameDescription
iint
Returns
TypeDescription
string

The name of the data type.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
DateTime

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
decimal

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
double

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
TypeDescription
IEnumerator

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

Overrides

GetFieldType(int)

public override Type GetFieldType(int i)

Gets the data type of the specified column.

Parameter
NameDescription
iint
Returns
TypeDescription
Type

The data type of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
ordinalint

The zero-based column ordinal.

Returns
TypeDescription
T

The value of the specified column.

Type Parameter
NameDescription
T

The type of the value to be returned.

Overrides
Exceptions
TypeDescription
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
NameDescription
columnNamestring

The name of the column whose value will be returned. Must not be null.

Returns
TypeDescription
T

The value of the column at the current row, converted to type T.

Type Parameter
NameDescription
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
NameDescription
iint
Returns
TypeDescription
float

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
Guid

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
short

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
int

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
long

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint

The index of the column whose value will be returned.

Returns
TypeDescription
Value

The raw protobuf as a Value.

Exceptions
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
string

The name of the specified column.

Overrides

GetNumeric(int)

public SpannerNumeric GetNumeric(int i)

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

Parameter
NameDescription
iint

The index of the column to retrieve.

Returns
TypeDescription
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
NameDescription
namestring

The name of the column.

Returns
TypeDescription
int

The zero-based column ordinal.

Overrides
Exceptions
TypeDescription
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
NameDescription
namestring

The name of the column.

cancellationTokenCancellationToken

A cancellation token to cancel reading metadata. Defaults to None.

Returns
TypeDescription
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
NameDescription
iint

The index of the column to retrieve.

Returns
TypeDescription
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
TypeDescription
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
NameDescription
cancellationTokenCancellationToken
Returns
TypeDescription
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
TypeDescription
DataTable

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

Overrides 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
NameDescription
iint

The index of the column to retrieve.

Returns
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
string

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
iint

The index of the column to retrieve.

Returns
TypeDescription
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
NameDescription
iint
Returns
TypeDescription
object

The value of the specified column.

Overrides
Exceptions
TypeDescription
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
NameDescription
valuesobject

An array of object into which to copy the attribute columns.

Returns
TypeDescription
int

The number of instances of object in the array.

Overrides

IsDBNull(int)

public override bool IsDBNull(int i)

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

Parameter
NameDescription
iint
Returns
TypeDescription
bool

true if the specified column is equivalent to DBNull; otherwise, false.

Overrides
Exceptions
TypeDescription
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
TypeDescription
bool

true if there are more result sets; otherwise, false.

Overrides

Read()

public override bool Read()

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

Returns
TypeDescription
bool

true if there are more rows; otherwise, false.

Overrides

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
NameDescription
cancellationTokenCancellationToken

A cancellation token to cancel the read. Cloud Spanner currently supports limited cancellation while advancing the read to the next row.

Returns
TypeDescription
Taskbool

True if another row was read.

Overrides