ibi™ Patterns - Search .NET Interface Overview. More...

Classes
class	BaseObjectStats
	Represents statistics that are common to all data objects. More...

class	ConfidenceQlt
	Holds additional data about a query needed for FirstValid score combiner. More...

class	NetricsArrayRecOpSrc
	An array backed source for record operations. More...

class	NetricsArrayRecSrc
	A simple array based implementation of the NetricsTableRecSrc interface. More...

class	NetricsBaseRecord
	The base class for all types of records used in the ibi™ Patterns - Search interface. More...

interface	NetricsBaseRecSrc
	Generic interface for reading records. More...

class	NetricsBaseThesaurus
	This is the base class for all of the thesaurus types. It should never be used directly. More...

class	NetricsCharmap
	Define a character map. More...

class	NetricsCharmapStats
	This class contains information about a character map in ibi™ Patterns - Search. More...

class	NetricsCmdStats
	This class contains summary statistics from the server on usage of a particular command. More...

class	NetricsCombinedThesaurus
	This class is used to define an ibi™ Patterns - Search Combined Thesaurus. More...

class	NetricsCompoundReader
	Read compound records from a set of record sources. More...

class	NetricsCompoundRecord
	A parent record with zero or more child records. More...

class	NetricsCompoundRecSrc
	Defines how compound records (parent plus children) are passed in the API. More...

class	NetricsConMgr
	Create connections to the ibi™ Patterns - Search Server. More...

class	NetricsCSVReader
	Implement NetricsFieldedReader for CSV files. More...

class	NetricsCSVRecSrc
	NetricsTableRecSrc implementation for CSV file records. More...

class	NetricsErrorItem
	Hold and provide access to detailed error information. More...

class	NetricsException
	A NetricsException is thrown whenever an error occurs. More...

interface	NetricsFieldedReader
	This interface is used to provide sets of fields to other ibi™ Patterns - Search classes. More...

class	NetricsFileFormatException
	Exceptions thrown by File Readers. More...

class	NetricsGpuDeviceInfo
	Contains information describing a GPU device attached to an ibi™ Patterns - Search Server. More...

class	NetricsIdxStats

class	NetricsJoin
	This class is used to define a join relationship for a Patterns search. More...

class	NetricsMappedRecord
	A NetricsMappedRecord inherits from a NetricsRecord, and has additional functionality which allows the user to access the fields of the record by field name or number. More...

class	NetricsModelStats
	Contains statistics about a Learn Model loaded into the ibi™ Patterns - Search server. More...

class	NetricsObjectNameCollection
	Holds the names of objects that can be stored in a ibi™ Patterns Server. More...

class	NetricsPredicate
	Search predicates are used to select or score records based on exact matching tests. More...

class	NetricsPsiEncoding
	Define encodings for the PSI prefilter. More...

class	NetricsQuery
	NetricsQuery objects are used to implement the complex query structures introduced with release 4.1. More...

class	NetricsRecFile
	Define name and format of a server side record source file. More...

class	NetricsRecOp
	Objects of this class associate a record operation with a record. More...

interface	NetricsRecOpSrc
	Generic interface for reading record operations. More...

class	NetricsRecord
	This class holds record data for an ibi™ Patterns - Search table. More...

class	NetricsRecSrcException
	Exceptions thrown by record sources. More...

class	NetricsSearchCfg
	This class is used with the search methods of the NetricsServerInterface class to configure a query. More...

class	NetricsSearchOpts
	This class is used to configure search options which apply for the overall search (for all tables being searched). More...

class	NetricsSearchResponse
	This class represents the ibi™ Patterns - Search Server's response to a search command. More...

class	NetricsSearchResult
	This class extends NetricsMappedRecord adding information relevant to a search result (match score, etc.). More...

class	NetricsServerInterface
	Base class for all interactions with the ibi™ Patterns - Search Server. More...

class	NetricsServerStats
	This class contains status information on the server process. More...

class	NetricsSortEncoding
	Define encodings for the SORT prefilter. More...

class	NetricsTable
	This class represents an ibi™ Patterns - Search table. More...

class	NetricsTableCursor
	This class is used to scan the records in a table. More...

class	NetricsTableCursorCompoundRecSrc
	Implements NetricsCompoundRecSrc by binding a NetricsTableCursor to a particular ibi™ Patterns - Search host. More...

class	NetricsTableCursorRecSrc
	Implements the NetricsTableRecSrc interface by binding a NetricsTableCursor to a particular ibi™ Patterns - Search host. More...

class	NetricsTableRecSrc

class	NetricsTableStats
	This class contains statistics on a table in the ibi™ Patterns - Search server. More...

class	NetricsTextFileRecSrc
	Text file record source for loading data. More...

class	NetricsThesaurus
	This class contains a list of synonyms that can be used while searching. More...

class	NetricsThesStats

class	NetricsTransaction
	This is an interface object associated with an explicit transaction. More...

class	NetricsTranStats
	Represents the status information on an open transaction. More...

class	NetricsVarAttr
	Manage a set of Variable Attribute values. More...

class	NetricsWeightedDictionary
	Objects of this class represent a weighted dictionary, used to define terms with lesser or greater importance. More...

Enumerations
enum	NetricsObjectType { TABLE = 0 , CHARMAP = 1 , THES = 2 , MODEL = 3 }
	Enumerates the types of objects that can be stored in a ibi™ Patterns Server. More...

Detailed Description

ibi™ Patterns - Search .NET Interface Overview.

The ibi™ Patterns - Search .NET interface is designed to interact with the ibi™ Patterns - Search Server. A ibi™ Patterns - Search Server may be a stand alone server or a gateway to a cluster of servers. The same .NET interface and the same methods are used to communicate with both.

Depending on the configuration of the particular ibi™ Patterns - Search Server not all methods available in the interface may be supported by the particular ibi™ Patterns - Search Server it is communicating with. Attempts to use a method that is not supported on the ibi™ Patterns - Search Server will cause the server to return an error, causing the .NET API to throw an exception.

This overview covers what is included with the .NET interface and a brief description of the interface at a high level.

Package Contents

The .NET interface package consists of the following:

NetricsServerInterface.dll A DLL file containing the complete server interface. No other DLL files are needed to use the .NET interface.
NetricsSample This directory contains a visual studio project for building a sample implementation of a simple utility for managing a ibi™ Patterns - Search Server. It also contains a User's Guide for the utility. This is sample code, the utility is not intended for production use and is not certified for such use.

The documentation for the .NET interface is included in the product documentation directory. It is provided in standard .NET HTML format.

Compatibility

The interface is compiled to be compatible with .NET 4.6.

Each release of the ibi™ Patterns - Search Server includes a new release of the .NET API. The .NET API release and the ibi™ Patterns - Search Server release should always be the same, the compatibility of a .NET API with a newer or older ibi™ Patterns - Search Server release is not guaranteed.

Related Documentation

This documentation is intended as a reference guide to the .NET interface. It is not intended to be a tutorial on using the ibi™ Patterns - Search Server or a complete reference on the features provided by the server. It is strongly recommended that you review the following documentation before using the .NET Interface.

ibi™ Patterns - Search Concept Guide. This document provides an overview of the ibi™ Patterns - Search Server, its features and how to use them. The .NET API reference documents assume the reader is familiar with the basic concepts presented in this guide.
ibi™ Patterns - Search Programmer's Guide. This document is both a reference manual for the "C" API and the most complete and detailed documentation on all of the features of the ibi™ Patterns - Search Server. The .NET API documentation is focused on describing the .NET API and doesn't necessarily fully describe the functionality of the associated ibi™ Patterns - Search Server feature. The ibi™ Patterns - Search Programmer's Guide focuses on documenting the functionality of the server. When questions arise concerning the behavior of the ibi™ Patterns - Search Server the ibi™ Patterns - Search Programmer's Guide> is the best reference.

Interface Overview

The .NET interface is organized into the following types of objects:

Connection Manager Objects hold all of the information needed to connect to a particular ibi™ Patterns - Search Server. Their purpose is to create Interface Objects used to communicate with the ibi™ Patterns - Search Server.
Interface Objects perform all interaction with the ibi™ Patterns - Search Server, they are the only objects that do so. All operations of the ibi™ Patterns - Search Server are exposed as method calls on these objects.
Exception Objects are extensions of the .NET Exception class and are used to report errors. All errors are reported via thrown exceptions.
Input Argument Objects represent arguments to methods of the Interface Objects. These objects don't communicate with the ibi™ Patterns - Search Server, they are holders of structured data, providing a convenient and controlled means of constructing or accessing that data.
Returned Data Objects represent results obtained from calls of Interface Object methods. These objects don't communicate with the ibi™ Patterns - Search Server, they are holders of structured data, providing a convenient and controlled means of accessing that data.
Record Handlers represent a record in a ibi™ Patterns - Search table, or a source that generates such records. Records are passed into and returned by the methods of Interface Objects, so in some sense they are both Input Argument Objects and Returned Data Objects.
File Handlers are used to read and parse files. Some of the other API classes use these classes to read files.

All of the public classes in the .NET API are listed below, grouped by the types described above.

Connection Manager Objects

There is only one class of this type: NetricsConMgr.

Interface Objects

NetricsServerInterface and NetricsTransaction are identical with one important distinction: all operations performed through a NetricsTransaction object are grouped together within a single transaction on the ibi™ Patterns - Search Server. When all operations to be associated with the transaction are complete they can be committed or aborted as a whole by calling one of the commitWork, forceCommitWork or abortWork methods provided by the NetricsTransaction class, after which the transaction is closed and the NetricsTransaction object will no longer accept commands.

The NetricsServerInterface object on the other hand performs each operation in a separate transaction, each being automatically committed or aborted (they are performed in implicit transactions as described in the ibi™ Patterns - Search Concept Guide).

There is one other difference between these two classes: to maintain backward compatibility NetricsServerInterface objects can be created directly through a set of public constructors, NetricsTransaction objects can only be created through the NetricsConMgr factory class.

These objects are for the most part stateless. Each method formats the data given and transmits it to the ibi™ Patterns - Search Server, reads the results and returns it to the caller. The data is not retained, nor is any state information retained in the interface objests. All data is maintained on the ibi™ Patterns - Search Server. Exceptions to this are: the necessary information needed to connect to the ibi™ Patterns - Search Server, logging and debugging settings, and, in the case of the NetricsTransaction class, information needed to identify the transaction it is associated with and whether the transaction has been closed or is still open.

Record Handlers

NetricsRecord
This represents a single record.
NetricsMappedRecord
This is an extension of NetricsRecord that allows record fields to be accessed by the associated table field names.
NetricsTableRecSrc
This is an interface that defines a generic source of NetricsRecords. Objects and methods that accept a set of records expect objects that implement this interface. By creating an implementation of the NetricsTableRecSrc interface and passing these to the .NET API the .NET API can read records directly from any source. For example an implementation of the NetricsTableRecSrc interface that read records from an Oracle table would allow records to be streamed direct from Oracle into the ibi™ Patterns - Search Server.
NetricsArrayRecSrc, NetricsCSVRecSrc
These are implementations of NetricsTableRecSrc for a simple internal array of records and for reading a CSV file of records respectively.

File Handlers

NetricsFieldedReader
This is an interface used by other classes in the .NET API when they must read fielded data from a file.
NetricsCSVReader
This is an implementation of the NetricsFieldedReader interface for standard format CSV files.

Exception Objects

NetricsException
Most errors are reported using NetricsException. All errors returned by the ibi™ Patterns - Search Server are reported as thrown NetricsException objects. Most errors generated by the .NET API itself are also reported by thrown NetricsExceptions.
NetricsErrorItem
This is a utility class used by the NetricsException class to expose data items returned by the ibi™ Patterns - Search Server in the error message.
NetricsFileFormatException
These are thrown by the file handler classes and the NetricsCSVRecSrc class. It provides file specific information such as line numbers, and character position.

Input Argument Objects

NetricsThesaurus, NetricsCombinedThesaurus, NetricsWeightedDictionary.
These represent the three types of thesaurus. They can hold the complete thesaurus definition or a reference to a file that contains the thesaurus data.
NetricsCharmap This represents the definition of a custom character map.
NetricsTable
This represents the definition of a table. The definition can also hold the records of a table as a NetricsTableRecSrc object. This is mostly used as an input argument but is also returned as a Returned Data Object by the table dump methods.
NetricsSearchCfg, NetricsQuery
These objects are used to define an inexact query. As inexact matching is the primary purpose of the ibi™ Patterns - Search Server these objects are key elements of the interface. A NetricsQuery object represents any of the basic query types. They are combined to create a complete query tree. NetricsSearchCfg is used to associate the query with a particular table. It also holds various table related options such as the filtering predicate to apply. Old style queries, now deprecated, are created using a NetricsSearchCfg object.
NetricsSearchOpts
This class defines the global search options to be associated with a query.
NetricsPredicate
This class is used to construct predicate expressions. It also provides various constants associated with predicate expressions. In most cases predicate expressions are now more easily constructed using predicate string expressions, but the methods provided by this class may be usefull in some cases.
NetricsRecFile
This class defines a file containing record information. It holds the file name and information on the format of the file.
NetricsVarAttr
This class is used to construct and parse the special variable attributes field values. A variable attributes field encodes an arbitrary set of name value pairs into a single record field.

All input argument objects should be created and initialized once, the same object should not be updated repeatedly. Think of them as constant data items.

Returned Data Objects

NetricsCharmapStats, NetricsTableStats, NetricsIdxStats, NetricsModelStats, NetricsThesStats
These classes hold settings and statistics on the various data items held in the ibi™ Patterns - Search Server. NetricsIdxStats holds information on the partitioned indexes within a table, so represents just a portion of a data item.
NetricsCmdStats
This holds the usage statistics for a single command. This is used for performance evaluation and monitoring.
NetricsSearchResponse, NetricsSearchResult
These contain the results of a search request. NetricsSearchResponse is the complete search response. It includes overall statistics plus an array of the records found, returned as an array of NetricsSearchResult items. A NetricsSearchResult item is an extension of NetricsMappedRecord that includes all of the scoring results from the search for that record.
NetricsServerStats
This contains the configuration information for the ibi™ Patterns - Search Server.
NetricsTranStats
This contains status information on one currently open transaction.

The classes: NetricsArrayDbRecSrc, NetricsDb, NetricsDbRecSrc NetricsDbSearchCfg and NetricsDbStats are old names for: NetricsArrayRecSrc, NetricsTable, NetricsTableRecSrc NetricsSearchCfg and NetricsTableStats respectively. They are all deprecated and shouldn't be used.

Examples

Here is a simple example of how to use the search method of the NetricsServerInterface class.
using System; using System.Collections.Generic; using System.Text; using System.IO; using NetricsServerInterface;

namespace Example1 {

// // Perform a simple query against a table. // We assume the table is loaded already. // class example1 {

public static void Main(String[] args) { // Get a connection to the server. // ----------------------------— // Here we use the legacy connection method, creating a // NetricsServerInterface object directly. We assume the // host and port are in first and second arguments. // Note: this call will NOT verify the connection. We won't know // if the server is there until we issue a command. int port = Convert.ToInt32(args[1]) ; NetricsServerInterface.NetricsServerInterface si = null ; si = new NetricsServerInterface.NetricsServerInterface(args[0], port) ;

// Define our input items String table_name = "city_names" ; String[] field_names = new String[] { "full name", "common name" } ; String query_str = "thecityoflakesalt" ;

// Create a query request // -------------------— // First we define a simple query. NetricsQuery qry = NetricsQuery.Simple(query_str, field_names, null) ; // Now we associate it with a table NetricsSearchCfg cfg = new NetricsSearchCfg(table_name) ; cfg.setNetricsQuery(qry) ;

// Perform the search, getting the results NetricsSearchResponse response = null ; try { response = si.search(cfg, null) ; } catch (NetricsException ne) { // Handle exception here Console.WriteLine("Search Call Failed: "+ne.ToString()) ; return ; } catch (IOException ioe) { // Handle IO exception here Console.WriteLine("Couldn't connect to server: "+ioe.ToString()) ; return ; }

// Print the record match score, key and full name for each record // ------------------------------------------------------------— // Get the list of records returned by the search. NetricsSearchResult[] results = response.getSearchResults() ; for ( int i = 0 ; i < results.Length ; i++ ) { // Print out the desired info for each record. Console.WriteLine("Score: "+results[i].getMatchScore()+ " Key: "+results[i].getKey()+ " Full Name: "+results[i].getField("full name") ) ; }

return ; }

}

The second example shows how to use a transaction to create and checkpoint a table.
using System; using System.Collections.Generic; using System.Text; using NetricsServerInterface;

namespace Example2 {

// Example 2: Create and load a table and checkpoint it in a // single transaction. class example2 {

public static void Main(String[] args) { // Start a Transaction. // -----------------— // Here we assume that either the default connection parameters // are used or they are defined in the environment (see NetricsConMgr). NetricsConMgr conmgr = new NetricsConMgr() ; // Now create our transaction Interface Object. // Note: this call will verify the connection, throwing an // exception if the server can't be contacted. NetricsTransaction tx = null ; try { tx = conmgr.beginWork() ; } catch (NetricsException ne) { // Handle error here. Console.WriteLine("Exception creating transaction: "+ne.ToString() ) ; return ; } catch (IOException ioe) { // Handle I/O errors, probably couldn't connect to server. Console.WriteLine("Couldn't connect to server: "+ioe.ToString() ) ; return ; } Console.WriteLine("Created Transaction: "+tx.getTranId() ) ;

String table_name = "city_names" ; String file_name = "city_names.csv" ;

// ----------------------------------------------— // We do all transaction operations in a try finally // block to make sure the transaction gets closed. // ----------------------------------------------— try {

// Create a table.
// --------------
// We load the table from a CSV file using the .NET API.
// (CSV files can also be read directly by the server.)
// The CSV file includes the field names as the first line
// in the file.  Our CSV file doesn't contain record keys,
// so we have the .NET API generate them.  This is the
// default record file configuration so we can use the
// basic constructor.
NetricsRecFile rec_file = new NetricsRecFile(file_name) ;

// Create a Record Source to read records from the CSV file.
NetricsCSVRecSrc rec_reader = null ;
try {
    rec_reader = new NetricsCSVRecSrc(rec_file) ;
} catch (FileNotFoundException nfe) {
    // Handle file not found or couln't be opened errors.
    Console.WriteLine(&quot;The file: &quot;+file_name+&quot; couldn't be opened: &quot;
                      +nfe.ToString() ) ;
    return ;
} catch (NetricsFileFormatException nffe) {
    // Handle CSV format errors.
    Console.WriteLine(&quot;The file &quot;+file_name
                      +&quot; has formatting errors: &quot;
                      +nffe.ToString() ) ;
    return ;
}

// Create a table definition.  This includes the record source.
// We get the field names from the record source.
NetricsTable table_def = new NetricsTable(table_name,
                                          rec_reader.getFieldNames(),
                                          rec_reader) ;

// Now we can create and load the table.
NetricsTableStats table_stats = null ;
try {
    table_stats = tx.tblload(table_def) ;
} catch (NetricsException ne) {
    // handle errors from server.
    Console.WriteLine(&quot;Table load failed: &quot;+ne.ToString() ) ;
    return ;
} catch (IOException ioe) {
    // handle communications errors.
    Console.WriteLine(&quot;Communications error: &quot;+ioe.ToString() );
    return ;
}

// Now checkpoint the table.
try {
    tx.checkpoint( new String[] { table_name } ) ;
} catch (NetricsException ne) {
    Console.WriteLine(&quot;Checkpoint failed: &quot;+ne.ToString() ) ;
    return ;
}

// And commit the transaction.
try {
    tx.commitWork() ;
    // transaction closed, null it out so we don't do so again.
    Console.WriteLine(&quot;Committed Transaction: &quot;+tx.getTranId() ) ;
    tx = null ;
} catch (NetricsException ne) {
    Console.WriteLine(&quot;Commit failed: &quot;+ne.ToString() ) ;
}

} finally { // ----------------------------------------------------------— // If we still have a transaction we errored out, abort it. // It is important to ensure that transactions are not left open. // Using a try-finally block can help ensure that transactions // are not left open. // ----------------------------------------------------------— if (tx != null) { try { tx.abortWork() ; Console.WriteLine("Aborted Transaction: "+tx.getTranId() ) ; tx = null ; } catch (NetricsException ne) { Console.WriteLine("Clean up abort failed: "+ne.ToString() ) ; } catch (IOException ioe) { Console.WriteLine("Clean up abort IO failed: " +ioe.ToString() ) ; } } }

return ; }

}

Enumeration Type Documentation

◆ NetricsObjectType

enum NetricsServerInterface.NetricsObjectType

Enumerates the types of objects that can be stored in a ibi™ Patterns Server.

Enumerator
TABLE	ibi™ Patterns - Search table objects.
CHARMAP	ibi™ Patterns - Search character-map objects.
THES	ibi™ Patterns - Search thesaurus objects.
MODEL	ibi™ Patterns - Search RLink model objects.

Classes

Enumerations

Detailed Description

Enumeration Type Documentation

◆ NetricsObjectType