OpenText Analytics Database 26.2.x – C#

Connecting-To: ADO.NET data types

Mon, 01 Jan 0001 00:00:00 +0000

This table details the mapping between OpenText™ Analytics Database data types and .NET and ADO.NET data types.

.NET Framework Type	ADO.NET DbType	VerticaType	OpenText™ Analytics Database Data Type	VerticaDataReader getter
Boolean	Boolean	Bit	Boolean	GetBoolean()
byte[]	Binary	Binary VarBinary LongVarBinary	Binary VarBinary LongVarBinary	GetBytes() Note The limit for LongVarBinary is 32 Million bytes. If you attempt to insert more than the limit during a batch transfer for any one row, then they entire batch fails. Verify the size of the data before attempting to insert a LongVarBinary during a batch.
Datetime	DateTime	Date Time TimeStamp	Date Time TimeStamp	GetDateTime() Note The Time portion of the DateTime object for database dates is set to DateTime.MinValue. Previously, VerticaType.DateTime was used for all date/time types. VerticaType.DateTime still exists for backwards compatibility, but now there are more specific VerticaTypes for each type.
DateTimeOffset	DateTimeOffset	TimestampTZ TimeTZ	TimestampTZ TimeTZ	GetDateTimeOffset() Note The Date portion of the DateTime is set to DateTime.MinValue
Decimal	Decimal	Numeric	Numeric	GetDecimal()
Double	Double	Double	Double Precision	GetDouble() Note The Double type uses a default precision of 53.
Int64	Int64	BigInt	Integer	GetInt64()
TimeSpan	Object	13 Interval Types	13 Interval Types	GetInterval() Note There are 13 VerticaType values for the 13 types of intervals. The specific VerticaType used determines the conversion rules that the driver applies. Year/Month intervals represented as 365/30 days
String	String	Varchar LongVarChar	Varchar LongVarChar	GetString()
String	StringFixedLengt	Char	Char	GetString()
Guid	Guid	UUID (see note below)	UUID	GetGuid()
Object	Object	N/A	N/A	GetValue()

UUID backwards compatibility

Vertica version 9.0.0 introduced the UUID data type, including JDBC support for UUIDs. The Vertica ADO.NET, ODBC, and OLE DB clients added full support for UUIDs in version 9.0.1. OpenText™ Analytics Database maintains backwards compatibility with older supported client driver versions that do not support the UUID data type, as follows:

When an older client...	OpenText™ Analytics Database...
Queries tables with UUID columns	Translates the native UUID values to CHAR values.
Inserts data into a UUID column	Converts the CHAR value sent by the client into a native UUID value.
Queries a UUID column's metadata	Reports its data type as CHAR.

Connecting-To: Setting the locale for ADO.NET sessions

Mon, 01 Jan 0001 00:00:00 +0000

ADO.NET applications use a UTF-16 character set encoding and are responsible for converting any non-UTF-16 encoded data to UTF-16. The same cautions as for ODBC apply if this encoding is violated.
The ADO.NET driver converts UTF-16 data to UTF-8 when passing to the OpenText™ Analytics Database server and converts data sent by the database server from UTF-8 to UTF-16.
ADO.NET applications should set the correct server session locale by executing the SET LOCALE TO command in order to get expected collation and string functions behavior on the server.
If there is no default session locale at the database level, ADO.NET applications need to set the correct server session locale by executing the SET LOCALE TO command in order to get expected collation and string functions behavior on the server. See the SET LOCALE command.

Connecting-To: Connecting to the database

Mon, 01 Jan 0001 00:00:00 +0000

Connecting-To: Querying the database using ADO.NET

Mon, 01 Jan 0001 00:00:00 +0000

This section describes how to create queries to do the following:

Note

The ExecuteNonQuery() method used to query the database returns an int32 with the number of rows affected by the query. The maximum size of an int32 type is a constant and is defined to be 2,147,483,547. If your query returns more results than the int32 max, then ADO.NET throws an exception because of the overflow of the int32 type. However the query is still processed by the database even when the reporting of the return value fails. This is a limitation in .NET, as ExecuteNonQuery() is part of the standard ADO.NET interface.

Connecting-To: Canceling ADO.NET queries

Mon, 01 Jan 0001 00:00:00 +0000

You can cancel a running vsql query by calling the .Cancel() method of any Command object. The SampleCancelTests class demonstrates how to cancel a query after reading a specified number of rows. It implements the following methods:

SampleCancelTest() executes the Setup() function to create a test table. Then, it calls RunQueryAndCancel() and RunSecondQuery() to demonstrate how to cancel a query after it reads a specified number of rows. Finally, it runs the Cleanup() function to drop the test table.
Setup() creates a database for the example queries.
Cleanup() drops the database.
RunQueryAndCancel() reads exactly 100 rows from a query that returns more than 100 rows.
RunSecondQuery() reads all rows from a query.

using System;
using Vertica.Data.VerticaClient;

class SampleCancelTests
{
    // Creates a database table, executes a query that cancels during a read loop,
    // executes a query that does not cancel, then drops the test database table.
    // connection: A connection to an OpenText&trade; Analytics Database.

    public static void SampleCancelTest(VerticaConnection connection)
    {
        VerticaCommand command = connection.CreateCommand();

        Setup(command);

        try
        {
            Console.WriteLine("Running query that will cancel after reading 100 rows...");
            RunQueryAndCancel(command);
            Console.WriteLine("Running a second query...");
            RunSecondQuery(command);
            Console.WriteLine("Finished!");
        }
        finally
        {
            Cleanup(command);
        }
    }

    // Set up the database table for the example.
    // command: A Command object used to execute the query.
    private static void Setup(VerticaCommand command)
    {
        // Create table used for test.
        Console.WriteLine("Creating and loading table...");
        command.CommandText = "DROP TABLE IF EXISTS adocanceltest";
        command.ExecuteNonQuery();
        command.CommandText = "CREATE TABLE adocanceltest(id INTEGER, time TIMESTAMP)";
        command.ExecuteNonQuery();
        command.CommandText = @"INSERT INTO adocanceltest
        SELECT row_number() OVER(), slice_time
            FROM(
                    SELECT slice_time FROM(
                    SELECT '2021-01-01'::timestamp s UNION ALL SELECT '2022-01-01'::timestamp s
                    ) sq TIMESERIES slice_time AS '1 second' OVER(ORDER BY s)
            ) sq2";
        command.ExecuteNonQuery();
    }

    // Clean up the database after running the example.
    // command: A Command object used to execute the query.
    private static void Cleanup(VerticaCommand command)
    {
        command.CommandText = "DROP TABLE IF EXISTS adocanceltest";
        command.ExecuteNonQuery();
    }

    // Execute a query that returns many rows and cancels after reading 100.
    // command: A Command object used to execute the query.
    private static void RunQueryAndCancel(VerticaCommand command)
    {
        command.CommandText = "SELECT COUNT(id) from adocanceltest";
        int fullRowCount = Convert.ToInt32(command.ExecuteScalar());

        command.CommandText = "SELECT id, time FROM adocanceltest";
        VerticaDataReader dr = command.ExecuteReader();
        int nCount = 0;
        try
        {
            while (dr.Read())
            {
                nCount++;
                if (nCount == 100)
                {
                    // After reaching 100 rows, cancel the command
                    // Note that it is not necessary to read the remaining rows
                    command.Cancel();
                    return;
                }
            }
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
        }
        finally
        {
            dr.Close();
            // Verify that the cancel stopped the query
            Console.WriteLine((fullRowCount - nCount) + " rows out of " + fullRowCount + " discarded by cancel");
        }
    }

    // Execute a simple query and read all results.
    // command: A Command object used to execute the query.
    private static void RunSecondQuery(VerticaCommand command)
    {
        command.CommandText = "SELECT 1 FROM dual";
        VerticaDataReader dr = command.ExecuteReader();
        try
        {
            while (dr.Read())
            {
                ;
            }
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Warning: no exception should be thrown on query after cancel");
        }
        finally
        {
            dr.Close();
        }
    }
}

Connecting-To: Handling messages

Mon, 01 Jan 0001 00:00:00 +0000

You can capture info and warning messages that OpenText™ Analytics Database provides to the ADO.NET driver by using the InfoMessage event on the VerticaConnection delegate class. This class captures messages that are not severe enough to force an exception to be triggered, but might still provide information that can benefit your application.

To use the VerticaInfoMessageEventHander class:

Create a method to handle the message sent from the even handler:

static void conn_InfoMessage(object sender, VerticaInfoMessageEventArgs e)
{
    Console.WriteLine(e.SqlState + ": " + e.Message);
}

Create a connection and register a new VerticaInfoMessageHandler delegate for the InfoMessage event:
```
_conn.InfoMessage += new VerticaInfoMessageEventHandler(conn_InfoMessage);
```
Execute your queries. If a message is generated, then the event handle function is run.

You can unsubscribe from the event with the following command:

_conn.InfoMessage -= new VerticaInfoMessageEventHandler(conn_InfoMessage);

Examples

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using Vertica.Data.VerticaClient;
namespace ConsoleApplication {
  class Program {
    // define message handler to deal with messages
    static void conn_InfoMessage(object sender, VerticaInfoMessageEventArgs e) {
      Console.WriteLine(e.SqlState + ": " + e.Message);
    }
    static void Main(string[] args) {
      //configure connection properties
      VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder();
      builder.Host = "192.168.1.10";
      builder.Database = "VMart";
      builder.User = "dbadmin";

      //open the connection
      VerticaConnection _conn = new VerticaConnection(builder.ToString());
      _conn.Open();

      //create message handler instance by subscribing it to the InfoMessage event of the connection
      _conn.InfoMessage += new VerticaInfoMessageEventHandler(conn_InfoMessage);

      //create and execute the command
      VerticaCommand cmd = _conn.CreateCommand();
      cmd.CommandText = "drop table if exists fakeTable";
      cmd.ExecuteNonQuery();

      //close the connection
      _conn.Close();
    }
  }
}

This examples displays the following when run:

00000: Nothing was dropped

Connecting-To: Getting table metadata

Mon, 01 Jan 0001 00:00:00 +0000

You can get the table metadata by using the GetSchema() method on a connection and loading the metadata into a DataTable:

database_name, schema_name, and table_name can be set to null, a specific name, or use a LIKE pattern.
table_type can be one of:
- "SYSTEM TABLE"
- "TABLE"
- "GLOBAL TEMPORARY"
- "LOCAL TEMPORARY"
- "VIEW"
- null
If table_type is null, then the metadata for all metadata tables is returned.

For example:

DataTable table = _conn.GetSchema("Tables", new string[] { null, null, null, "SYSTEM TABLE" });

Examples

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using Vertica.Data.VerticaClient;
namespace ConsoleApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            // configure connection properties
            VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder();
            builder.Host = "192.168.1.10";
            builder.Database = "VMart";
            builder.User = "dbadmin";

            // open the connection
            VerticaConnection _conn = new VerticaConnection(builder.ToString());
            _conn.Open();

            // create a new data table containing the schema
            // the last argument can be "SYSTEM TABLE", "TABLE", "GLOBAL TEMPORARY",
            // "LOCAL TEMPORARY", "VIEW", or null for all types
            DataTable table = _conn.GetSchema("Tables", new string[] { null, null, null, "SYSTEM TABLE" });

            // print out the schema
            foreach (DataRow row in table.Rows) {
                foreach (DataColumn col in table.Columns)
                {
                    Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);
                }
                Console.WriteLine("============================");
            }

            //close the connection
            _conn.Close();
        }
    }
}