This Clusterpoint Wiki site is deprecated!
For reference - please refer to our new Wiki site at:

.NET API overview

From Clusterpoint Wiki
Jump to: navigation, search

The CPS .NET API provides easier access to CPS from .NET. Some of the key concepts of using the API are outlined here. Code samples will be given in C# language, but library in binary form can be used from any .NET language. Library itself is written in C#.

Required includes

All CPS .NET API functions is located in CPS namespace. So most probably you will need to specify this namespace.

using CPS;

There are two versions of API available - CPS_Simple and full CPS. If You don't know yet, which API You are going to use - read on, this document describes the difference between the two.


Before sending any requests, You have to create an instance of the CPS_Connection class. For its constructor You have to specify:

1) The connection string.
There is no ability to use UNIX socket from .NET library as this is available on Unix systems only. If You are connecting to a TCP socket, You should prefix the hostname with a tcp:// prefix. Also, You can specify a port number if it differs from the default one, e.g.:


If You are connecting over HTTP (lowest performance), You should specify the full URL to the HTTP gateway, including the http:// prefix, e.g.:


2) The database name
3) Username for authentication
4) Password for authentication
5) (optional) Document root tag name. This is only required if Your document root tag name is not "document"
6) (optional) Document ID Xpath. This is only required if Your document ID xpath, as specified in the database policy, is not "/document/id". You have to specify the full path from the root, including the root tag, separated by slashes, e.g.


7) Dictionary with additional envelope parameters. When connecting to Clusterpoint Cloud Account ID should be specified.

An example connection:

CPS_Connection cpsConnection = new CPS_Connection(
    "tcp://SERVER_IP:SERVER_PORT", "database", "username", "password", "document", 
    "/document/id", new Dictionary<string, string>(){{"account", "<YOUR_ACCOUNT_ID>"}});

Note, that depending on Cloud server you are registered in, you should indicate server {REGION} - US or EU. For example:

using CPS;
CPS_Connection cpsConnection = new CPS_Connection(
	"tcp://", "example", "username", "password", "document", "/document/id",
	new Dictionary<string, string>(){{"account", "<YOUR_ACCOUNT_ID>"}}
CPS_Simple cps = new CPS_Simple(cpsConnection);

.NET CPS API vs CPS_Simple

Two APIs are actually provided. If You are new to CPS, it's probably better to try the CPS_Simple API first, as it is much easier to use, and only to progress to the full CPS API when necessary.


The first one is the .NET CPS API that essentially provides the same amount of functionality as the XML API - You can send any command with any request options specified. In this API, for each request to the database You have to:
1) Create a request object - there are different types of request objects suited for different commands, e.g. CPS_SearchRequest class is for the 'search' command.
2) Set all the parameters for this request object with provided method (e.g. group parameters for search can be set with the CPS_SearchRequest.setGroup method, etc.)
3) Send the request using the CPS_Connection.sendRequest method. The method will return a response object, e.g. CPS_SearchResponse
4) Retrieve the required information from the response object using its methods, e.g. CPS_SearchResponse.getDocuments, CPS_SearchResponse.getFacets

using CPS;
CPS_Connection cpsConnection = new CPS_Connection(
    "tcp://SERVER_IP:SERVER_PORT", "example", "username", "password", "document", 
    "/document/id", new Dictionary<string, string>(){{"account", "<YOUR_ACCOUNT_ID>"}});
CPS_SearchRequest searchRequest = new CPS_SearchRequest("test*", 0, 0);
CPS_SearchResponse searchResponse = (CPS_SearchResponse)cpsConnection.sendRequest(searchRequest);
Dictionary<string, Dictionary<string, int>> facets = searchResponse.getFacets();

CPS_Simple API

This API option is suited for a majority of requests that don't require advanced parameters to be specified, and that only return a single type of data. This API is very simple to use, however there is a cost to that simplicity - through this API You don't have access to some advanced functionality of the CP database, such as facets, grouping and some other features that require explicitly specifying request parameters for the database.
In order to use this API, You have to instantiate a CPS_Simple object with a CPS_Connection object as an argument, e.g.

CPS_Simple cps = new CPS_Simple(cpsConnection);

The CPS_Simple API now can simply be used by calling the methods of the CPS_Simple class, for example:

Dictionary<string, XmlElement> documents = (Dictionary<string, XmlElement>)"test*");



Error handling

All CPS objects will throw exceptions of type CPS_Exception upon receiving error with at least REJECTED level from the CP database, as well as upon receiving some invalid parameters (e.g. malformed documents). In order to prevent the exception from being shown to the user of Your application, it is advised to place all code dealing with CPS objects into a try-catch block, e.g.:

using CPS;
    CPS_Connection cpsConnection = new CPS_Connection(
        "tcp://SERVER_IP:SERVER_PORT", "example", "username", "password", "document", 
        "/document/id", new Dictionary<string, string>(){{"account", "<YOUR_ACCOUNT_ID>"}});
    CPS_Simple cps = new CPS_Simple(cpsConnection);
    Dictionary<string, XmlElement> documents = (Dictionary<string, XmlElement>)"test*");
catch (CPS_Exception ex)

Errors, that were returned from the database with level lower than REJECTED is stored in response object and can be retrieved using CPS_Response.getErrors method.

Note that multi-document modifying requests might return errors only for some of the document IDs, while the rest of the modifications will take place successfully. In order to detect these situations, You can check the document_id field inside the error array.

Request and response parameter formats

All requests and response methods accepts parameters and returns results only in specified types - string, List<>, Dictionary<>, XmlElement etc. Accepted types are described in each method documentation. Sometimes string parameter must be in specific format. Specifying wrong type and/or format will cause an exception. For example, multiple types are supported for specifying and retrieving document contents. These requirements are outlined here.

Search query

The search query is one of the fields that is specified as a raw XML string, so that complex querying is possible through the API. Due to this You have to either escape <, >, & characters in Your queries or compose the query using the helper functions Utils.CPS_QueryTerm and Utils.CPS_Term. The difference between these functions is that CPS_QueryTerm also escapes all search operators in a given term. This could be useful if You are passing the query directly from the user into the query string.

// string query = "{<xpath1>$term$</xpath1><xpath2>term2</xpath2>}";
string query = "{" + Utils.CPS_Term("$term1$", "xpath1") + Utils.CPS_Term("term2", "xpath2") + "}";
// string query = "{<xpath1><subxpath1>term1</subxpath1></xpath1><xpath2>term2</xpath2>}"; 
string query = "{" + Utils.CPS_Term("term1", "xpath1/subxpath1") + CPS_Term("term2", "xpath2") + "}"; 
// string query = "{<xpath1>\$term\$</xpath1><xpath2>term2</xpath2>}";
string query = "{" + Utils.CPS_QueryTerm("$term$", "xpath1") + CPS_Term("term2", "xpath2") + "}";
// string query = "<xpath1>&gt;5</xpath1>";
string query = Utils.CPS_Term(">5", "xpath1");
Dictionary<string, XmlElement> documents = (Dictionary<string, XmlElement>);

Search ordering parameters

Search ordering parameters could be specified as an XML string or an List of strings, but it is also possible to specify them completely using the helper functions Utils.CPS_RelevanceOrdering, Utils.CPS_NumericOrdering, Utils.CPS_LatLonDistanceOrdering and Utils.CPS_PlaneDistanceOrdering.
For example, the following request will return results ordered by the fields user_count in a descending order. If user_count is equal for several documents, they will be sorted by relevance among themselves:

CPS_SearchRequest searchRequest = new CPS_SearchRequest("query");
List<string> order = new List<string>();
order.Add(Utils.CPS_NumericOrdering("user_count", "descending"));
CPS_SearchResponse searchResponse = (CPS_SearchResponse)cpsConnection.sendRequest(searchRequest);

Document contents

Document contents can be specified and retrieved in 2 different types. Where You place document contents in the request, the type of the document contents will be detected automatically. When retrieving document contents from a request, relevant API calls have a returnType parameter, which can specify the document content type that would be returned. The following types are supported:
1) XmlElement nodes. This is the default, DOC_TYPE is DOC_TYPE_STDCLASS, .NET native object for representing XML nodes. Fields can be easily retrieved and set, e.g. the following example retrieves documents from the database and replaces a certain field:

// creating CPS_Simple object from an existing CPS_Connection object
CPS_Simple cpsSimple = new CPS_Simple(cpsConnection);
// specifying an array of document IDs to retrieve
List<string> ids = new List<string>();
// initializing the array for the update request
Dictionary<string, XmlElement> update_docs = new Dictionary<string, XmlElement>();
Dictionary<string, XmlElement> retrieved_docs = (Dictionary<string, XmlElement>)cpsSimple.retrieveMultiple(ids);
foreach (KeyValuePair<string, XmlElement> pair in retrieved_docs)
    foreach (XmlElement tag in pair.Value.ChildNodes)
        // for documents that don't have the <b> tags already
        if (tag.Name == "title" && tag.InnerXml.Substring(0, 3) != "<b>")
            // change document title
            tag.InnerXml = "<b>" + tag.InnerXml + "</b>";
            // store document for update
            update_docs[pair.Key] = pair.Value;
// run the update command on these documents

2) CPS_SimpleXML nodes. This format can be selected by setting the returnType argument to DOC_TYPE_SIMPLEXML. This class is very similar to PHP's simpleXML class and is intended for very simple use. Because class is read-only, it can be used mostly for read operations. If you need to change existing values, class can be easy converted to XmlElement using CPS_SimpleXML.ConvertToXML method. Class is constructed from XmlElement class, so you can create it at any time, if you wish.

// creating CPS_Simple object from an existing CPS_Connection object
CPS_Simple cpsSimple = new CPS_Simple(cpsConnection);
// retrieving single document with id = id1
CPS_SimpleXML document = (CPS_SimpleXML)cpsSimple.retrieveSingle("id1", CPS_Response.DOC_TYPE.DOC_TYPE_SIMPLEXML);
// display result to user
display_result_to_user(document["title"] + "\r\n" + document["text"]);

3) There is third option for DOC_TYPE - DOC_TYPE_ARRAY, but currently it is not supported. It is intended for future functionality.

List parameter

The list parameter specifies which fields are to be returned for list-last, list-first and search requests. This parameter is optional and (if specified) will be merged with defined database policy. It can be specified with a Dictionary<string, string> with xpaths of the fields as keys and listing options as values. E.g.

// creating CPS_Simple object from an existing CPS_Connection object
CPS_Simple cpsSimple = new CPS_Simple(cpsConnection);
// lists the document tag and all tags under it, except for the text/full_text tag
Dictionary<string, string> list = new Dictionary<string, string>();
list["document"] = "yes";
list["text/full_text"] = "no";
// listing last 10 documents
Dictionary<string, CPS_SimpleXML> documents = (Dictionary<string, CPS_SimpleXML>)cpsSimple.listLast(list, 0, 10, CPS_Response.DOC_TYPE.DOC_TYPE_SIMPLEXML);

Further reading

More information can be obtained by reading the .NET API Reference, as well as .NET API usage examples for each particular command in the Wiki manual and Clusterpoint API Code Samples.