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 3.5.
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.
Connection Manager Objects
There is only one class of this type: NetricsConMgr.
Interface Objects
- NetricsServerInterface
- NetricsTransaction
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, NetricsDbRecSrcNetricsDbSearchCfg and NetricsDbStats are old names for: NetricsArrayRecSrc, NetricsTable, NetricsTableRecSrcNetricsSearchCfg 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.
 Copy Code
| |
|---|---|
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.
| Copy Code
| |
|---|---|
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("The file: "+file_name+" couldn't be opened: "
+nfe.ToString() ) ;
return ;
} catch (NetricsFileFormatException nffe) {
// Handle CSV format errors.
Console.WriteLine("The file "+file_name
+" has formatting errors: "
+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("Table load failed: "+ne.ToString() ) ;
return ;
} catch (IOException ioe) {
// handle communications errors.
Console.WriteLine("Communications error: "+ioe.ToString() );
return ;
}
// Now checkpoint the table.
try {
tx.checkpoint( new String [] { table_name } ) ;
} catch (NetricsException ne) {
Console.WriteLine("Checkpoint failed: "+ne.ToString() ) ;
return ;
}
// And commit the transaction.
try {
tx.commitWork() ;
// transaction closed, null it out so we don't do so again.
Console.WriteLine("Committed Transaction: "+tx.getTranId() ) ;
tx = null ;
} catch (NetricsException ne) {
Console.WriteLine("Commit failed: "+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 ;
}
}
}
| |
Classes
| Class | Description | |
|---|---|---|
|
BaseObjectStats | Represents statistics that are common to all data objects. This class is abstract (MustInherit in Visual Basic)abstractMustInherit and so cannot be instantiated. |
|
|
ConfidenceQlt | Holds additional data about a query needed for FirstValid score combiner. |
|
|
NetricsArrayRecOpSrc | An array backed source for record operations. |
|
|
NetricsArrayRecSrc | A simple array based implementation of the NetricsTableRecSrc interface. |
|
|
NetricsBaseRecord | |
|
|
NetricsBaseThesaurus | This is the base class for all of the thesaurus types. It should never be used directly. |
|
|
NetricsCharmap | Define a character map. |
|
|
NetricsCharmapStats | This class contains information about a character map in ibi™ Patterns - Search. |
|
|
NetricsCmdStats | This class contains summary statistics from the server on usage of a particular command. |
|
|
NetricsCombinedThesaurus | This class is used to define an ibi™ Patterns - Search Combined Thesaurus. |
|
|
NetricsCompoundReader | Read compound records from a set of record sources. |
|
|
NetricsCompoundRecord | A parent record with zero or more child records. |
|
|
NetricsCompoundRecSrc | /** Defines how compound records (parent plus children) are passed in the API. This class is abstract (MustInherit in Visual Basic)abstractMustInherit and so cannot be instantiated. |
|
|
NetricsConMgr | Create connections to the ibi™ Patterns - Search Server. |
|
|
NetricsCSVReader | Implement NetricsFieldedReader for CSV files. |
|
|
NetricsCSVRecSrc | NetricsTableRecSrc implementation for CSV file records. |
|
|
NetricsErrorItem | Hold and provide access to detailed error information. |
|
|
NetricsException | A NetricsException is thrown whenever an error occurs. |
|
|
NetricsFileFormatException | Exceptions thrown by File Readers. |
|
|
NetricsGpuDeviceInfo | Contains information describing a GPU device attached to an ibi™ Patterns - Search Server. |
|
|
NetricsIdxStats | This class contains statistics about a partitioned index in the ibi™ Patterns - Search server. |
|
|
NetricsJoin | This class is used to define a join relationship for a Patterns search. |
|
|
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. |
|
|
NetricsModelStats | This class contains stats about a Learn Model loaded into the ibi™ Patterns - Search server. |
|
|
NetricsObjectNameCollection | Holds the names of objects that can be stored in an ibi Patterns Server. This class cannot be inherited. |
|
|
NetricsPredicate | Search predicates are used to select or score records based on exact matching tests. |
|
|
NetricsPredicateMapper | Remap field names and data values in a predicate string. |
|
|
NetricsPsiEncoding | Define encodings for the PSI prefilter. |
|
|
NetricsQuery | NetricsQuery objects are used to implement the complex query structures introduced with release 4.1. |
|
|
NetricsRecFile | Define name and format of a server side record source file. |
|
|
NetricsRecOp | Objects of this class associate a record operation with a record. |
|
|
NetricsRecord | This class holds record data for an ibi™ Patterns - Search table. |
|
|
NetricsSearchCfg | This class is used with the search methods of the NetricsServerInterface class to configure a query. |
|
|
NetricsSearchOpts | This class is used to configure search options which apply for the overall search (for all tables being searched). |
|
|
NetricsSearchResponse | This class represents the ibi™ Patterns - Search Server's response to a search command. |
|
|
NetricsSearchResult | This class extends NetricsMappedRecord adding information relevant to a search result (match score, etc.). |
|
|
NetricsServerInterface | Base class for all interactions with the ibi™ Patterns - Search Server. |
|
|
NetricsServerStats | This class contains status information on the server process. |
|
|
NetricsSortEncoding | Define encodings for the SORT prefilter. |
|
|
NetricsTable | This class represents an ibi™ Patterns - Search table. |
|
|
NetricsTableCursor | This class is used to scan the records in a table. |
|
|
NetricsTableCursorCompoundRecSrc | Implements |
|
|
NetricsTableCursorRecSrc | Implements the |
|
|
NetricsTableRecSrc | |
|
|
NetricsTableStats | This class contains statistics on a table in the ibi™ Patterns - Search server. |
|
|
NetricsTextFileRecSrc | Text file record source for loading data. |
|
|
NetricsThesaurus | This class contains a list of synonyms that can be used while searching. |
|
|
NetricsThesStats | This class contains information about a thesaurus on the ibi™ Patterns - Search server. |
|
|
NetricsTransaction | This is an interface object associated with an explicit transaction. This class cannot be inherited. |
|
|
NetricsTranStats | Represents the status information on an open transaction. |
|
|
NetricsVarAttr | Manage a set of Variable Attribute values. |
|
|
NetricsWeightedDictionary | Objects of this class represent a weighted dictionary, used to define terms with lesser or greater importance. |
Interfaces
| Interface | Description | |
|---|---|---|
|
NetricsBaseRecSrc | Generic interface for reading records. |
|
|
NetricsFieldedReader | This interface is used to provide sets of fields to other ibi™ Patterns - Search classes. |
|
|
NetricsRecOpSrc | Generic interface for reading record operations. |
Enumerations
| Enumeration | Description | |
|---|---|---|
|
NetricsConMgr.ProtocolChoice | |
|
|
NetricsException.error_codes | An enumeration of all error codes returned as part of the NetricsException object. |
|
|
NetricsObjectType | Enumerates the types of objects that can be stored in an ibi Patterns Server. |
|
|
NetricsPredicate.DistanceUnits | Units of measure for distance functions. |
|
|
NetricsPredicate.pred_ops | An enumeration of all the predicate operators. |
|
|
NetricsRecOp.Op | This defines the known record operations. |
|
|
NetricsRecord.ChildType | The different types of child records. |
|
|
NetricsSearchOpts.score_types | An enumeration of all possible score types. |
|
|
NetricsSearchOpts.tiebreak_types | An enumeration of all possible tiebreak types. |
|
|
NetricsServerInterface.ConnectionPoolingPolicy | Possible connection pooling policies. |
|
|
NetricsServerInterface.ShutdownStatus | Shutdown the ibi™ Patterns - Search Server. |
|
|
NetricsTable.field_typs | An enumeration of all the field types. |
|
|
NetricsTable.PsiDensity | Allowed density settings for PSI prefilters. |