Table Of Contents

7.11. .NET

7.11.1. Introduction

Welcome the Quasardb API for .NET.

7.11.2. Connecting to the database

Interfacing with a quasardb database from a .NET program is extremely straightforward, just create a QdbCluster and perform the operations.

var cluster = new QdbCluster("qdb://127.0.0.1:2836");
Dim cluster = New QdbCluster("qdb://127.0.0.1:2836");

7.11.3. Blobs

OK, now that we have a connection to the database, let’s store some binary data:

byte[] a, b, c;

QdbBlob myBlob = cluster.Blob("Bob the blob");

myBlob.Put(a);
myBlob.Update(b);
c = myBlob.Get();
Dim a, b, c As Byte()

Dim myBlob = cluster.Blob("Bob the blob")

myBlob.Put(a)
myBlob.Update(b)
c = myBlob.Get()

7.11.4. Double-ended queues

Quasardb provides double-ended queues, or simply “deque”.

byte[] a, b, c;

QdbDeque myQueue = cluster.Deque("Andrew the queue");

myQueue.PushBack(a);
myQueue.PushBack(b);
c = myQueue.PopFront();
Dim a, b, c As Byte()

Dim myQueue = cluster.Deque("Andrew the queue")

myQueue.PushBack(a)
myQueue.PushBack(b)
c = myQueue.PopFront()

7.11.5. Integers

quasardb comes out of the box with server-side atomic integers:

long a, b, c;

QdbInteger myInt = cluster.Integer("Roger the integer");

myInt.Put(a);
c = myInt.Add(b);
Dim a, b, c As Long

Dim myInt = cluster.Integer("Roger the integer")

myInt.Put(a)
c = myInt.Add(b)

7.11.6. Streams

A stream is basically a scalable blob with inifinite size. It’s recommended to use a stream above 10MB.

Stream myStream = cluster.Stream("Aline the stream").Open(QdbStreamMode.Append);
// now you have a regular C# stream:
myStream.Write(data, 0, data.Length);
await myStream.WriteAsync(data, 0, data.Length);

7.11.7. Tags

Here’s how you can easily find your data, using tags:

cluster.Blob("Bob the blob").AttachTag("Male");
cluster.Integer("Roger the integer").AttachTag("Male");

IEnumerable<QdbEntry> males = cluster.Tag("Male").GetEntries();
cluster.Blob("Bob the blob").AttachTag("Male");
cluster.Integer("Roger the integer").AttachTag("Male");

Dim males = cluster.Tag("Males").GetEntries()

7.11.8. Search by prefix or suffix

And here, you can find your data searching by prefix or suffix:

cluster.Blob("Hey! Bob the blob. Bye.");
cluster.Integer("Hey! Roger the integer. Bye.");

IEnumerable<QdbEntry> heys = cluster.Entries(new QdbPrefixSelector("Hey!", 10));
IEnumerable<QdbEntry> byes = cluster.Entries(new QdbSuffixSelector("Bye.", 10));
cluster.Blob("Hey! Bob the blob");
cluster.Integer("Hey! Roger the integer");

Dim heys = cluster.Entries(New QdbPrefixSelector("Hey!", 10))
Dim byes = cluster.Entries(New QdbSuffixSelector("Bye.", 10))

Instead of getting the entries as the result, one can ask only for a collection of strings using Keys() method instead of Entries().

cluster.Blob("Hey! Bob the blob. Bye.");
cluster.Integer("Hey! Roger the integer. Bye.");

IEnumerable<String> heys = cluster.Keys(new QdbPrefixSelector("Hey!", 10));
IEnumerable<String> byes = cluster.Keys(new QdbSuffixSelector("Bye.", 10));
cluster.Blob("Hey! Bob the blob");
cluster.Integer("Hey! Roger the integer");

Dim heys = cluster.Keys(New QdbPrefixSelector("Hey!", 10))
Dim byes = cluster.Keys(New QdbSuffixSelector("Bye.", 10))

7.11.9. See Also (References):

Cluster

class Quasardb::QdbCluster

A connection to a quasardb database.

Inherits from IDisposable

Public Functions

Quasardb.QdbCluster.QdbCluster(string uri)

Connects to a quasardb database.

Parameters
  • uri: The URI of the quasardb database.

Quasardb.QdbCluster.QdbCluster(string uri, string clusterPublicKey, string userName, string userPrivateKey)

Connects securely to a quasardb database.

Parameters
  • uri: The URI of the quasardb database.
  • clusterPublicKey: Cluster public key used for database authentication.
  • userName: User name used for connection.
  • userPrivateKey: User private key used for connection.

void Quasardb.QdbCluster.SetCompression(QdbCompression level)

Set the compression level.

void Quasardb.QdbCluster.Dispose()

Close the connection to the database.

QdbBlob Quasardb.QdbCluster.Blob(string alias)

Returns a QdbBlob attached to the specified alias.

No operation is performed in the database.

Return
A blob associated to the specified alias.
See
QdbBlob
Parameters
  • alias: The alias (i.e. key) of the blob in the database.

IEnumerable<QdbBlob> Quasardb.QdbCluster.Blobs(IQdbBlobSelector selector)

Returns a collection of QdbBlob matching the given criteria.

Return
A collection of blob matching the criteria.
Parameters
  • selector: The criteria to filter the blobs.

QdbEntry Quasardb.QdbCluster.Entry(string alias)

Returns a QdbEntry attached to the specified alias. The actual type of the return value depends on the type of the entry in the database.

Return
An entry associated to the specified alias.
Parameters
  • alias
Exceptions
  • QdbAliasNotFoundException: If the entry doesn’t exists.

IEnumerable<QdbEntry> Quasardb.QdbCluster.Entries(IQdbEntrySelector selector)

Returns a collection of QdbEntry matching the given criteria.

Return
A collection of entry.
Parameters
  • selector: The criteria to filter the entries

IEnumerable<String> Quasardb.QdbCluster.Keys(IQdbEntrySelector selector)

Returns a collection of String matching the given criteria.

Return
A collection of entry.
Parameters
  • selector: The criteria to filter the entries

QdbInteger Quasardb.QdbCluster.Integer(string alias)

Returns a QdbInteger attached to the specified alias.

No operation is performed in the database.

Return
An integer associated to the specified alias.
See
QdbInteger
Parameters
  • alias: The alias (i.e. key) of the integer in the database.

QdbStream Quasardb.QdbCluster.Stream(string alias)

Returns a QdbStream attached to the specified alias.

Return
A stream attached to the specified alias.
Parameters
  • alias: The alias (i.e. key) of the stream in the database
Exceptions
  • ArgumentNullException

QdbTag Quasardb.QdbCluster.Tag(string alias)

Returns a QdbTag attached to the specified alias.

No operation is performed in the database.

Return
A tag associated to the specified alias.
See
QdbTag
Parameters
  • alias: The alias (i.e. key) of the tag in the database.

void Quasardb.QdbCluster.RunBatch(QdbBatch batch)

Executes the operations contained in the batch.

Parameters
  • batch: The collection of operation to execute.

QdbTimeSeries Quasardb.QdbCluster.TimeSeries(string alias)

Returns a QdbTimeSeries attached to the specified alias.

No operation is performed in the database.

Return
A time series associated to the specified alias.
See
QdbTimeSeries
Parameters
  • alias: The alias (i.e. key) of the time series in the database.

Blobs

class Quasardb::QdbBlob

A blob (unstructured data) in a quasardb database.

QdbBlob can be constructed via QdbCluster.Blob.

Here is how to put a blob in the database:

byte[] myData;
var cluster = new QdbCluster("qdb://127.0.0.1:2836");

cluster.Blob("some name").Put(myData);
Dim myData As Byte()
Dim cluster = New QdbCluster("qdb://127.0.0.1:2836")

cluster.Blob("some name").Put(myData)

Inherits from Quasardb.QdbExpirableEntry

Public Functions

byte [] Quasardb.QdbBlob.CompareAndSwap(byte[] content, byte[] comparand, DateTime? expiryTime = null)

Atomically compares and replaces the content when it matches.

Return
The previous content of the blob if it didn’t match; null if it matched.
Parameters
  • content: The new content to put in the blob.
  • comparand: The content to be compared to.
  • expiryTime: The expiry time to set if the blob’s content is replaced.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

byte [] Quasardb.QdbBlob.Get()

Gets the content.

Return
The current content of the blob.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

byte [] Quasardb.QdbBlob.GetAndRemove()

Atomically gets the content and delete the blob.

Return
The previous content of the blob.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

byte [] Quasardb.QdbBlob.GetAndUpdate(byte[] content, DateTime? expiryTime = null)

Atomically gets the content and replaces it.

Return
The previous content of the blob.
Parameters
  • content: The new content of the blob.
  • expiryTime: The new expiry time of the blob.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

void Quasardb.QdbBlob.Put(byte[] content, DateTime? expiryTime = null)

Sets the content, but fails if the blob already exists.

Parameters
  • content: The new content of the blob.
  • expiryTime: The expiry time to set.
Exceptions
  • QdbAliasAlreadyExistsException: The entry already exists.

bool Quasardb.QdbBlob.RemoveIf(byte[] comparand)

Atomically compares the content and deletes the blob when it matches.

Return
true if remove, false if not.
Parameters
  • comparand: The content to compare to.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

bool Quasardb.QdbBlob.Update(byte[] content, DateTime? expiryTime = null)

Replaces the content.

Return
true if the blob has been created, or false if it has been replaced.
Parameters
  • content: The new content of the blob.
  • expiryTime: The expiry time to set.
Exceptions
  • QdbAliasNotFoundException: The blob is not present in the database.
  • QdbIncompatibleTypeException: The database entry is not a blob.

Deque

Warning

doxygenclass: Cannot find class “Quasardb::QdbDeque” in doxygen xml output for project “qdb_dotnetapi” from directory: ../../apis/dotnet/output/xml

Integer

class Quasardb::QdbInteger

An atomic integer in the database.

Here is how to set an integer blob in the database:

var cluster = new QdbCluster("qdb://127.0.0.1:2836");

cluster.Integer("some name").Put(42);
Dim cluster = New QdbCluster("qdb://127.0.0.1:2836")

cluster.Integer("some name").Put(42)

Inherits from Quasardb.QdbExpirableEntry

Public Functions

long Quasardb.QdbInteger.Add(long addend)

Modifies the value of the integer in the database.

Return
The new value of the integer in the database.
Parameters
  • addend: The value to add.
Exceptions
  • QdbAliasNotFoundException: The integer doesn’t exist in the database.
  • QdbIncompatibleTypeException: The entry in the database is not an integer.

long Quasardb.QdbInteger.Get()

Gets the value of the integer in the database.

Return
The value of the integer in the database.
Exceptions
  • QdbAliasNotFoundException: The integer doesn’t exist in the database.
  • QdbIncompatibleTypeException: The entry in the database is not an integer.

void Quasardb.QdbInteger.Put(long value, DateTime? expiryTime = null)

Sets the value of the integer, fails if it already exists.

Parameters
  • value: The initial value of the new integer.
  • expiryTime: The expiry time of the integer.
Exceptions
  • QdbAliasAlreadyExistsException: The entry already exists in the database./

bool Quasardb.QdbInteger.Update(long value, DateTime? expiryTime = null)

Sets the value of the integer, fails if it already exists.

Return
true if the integer has been created, or false if it has been replaced.
Parameters
  • value: The new value of the integer.
  • expiryTime: The expiry time of the integer.
Exceptions
  • QdbIncompatibleTypeException: The entry in the database is not an integer.

Stream

class Quasardb::QdbStream

A stream in the database.

Here is how to write or read data to a stream:

byte[] myData;
var cluster = new QdbCluster("qdb://127.0.0.1:2836");

// To write to a stream:
using (var stream = cluster.Stream("some name").Open(QdbStreamMode.Append))
{
    stream.Write(myData, 0, myData.Length);
}

// To read from a stream:
using (var stream = cluster.Stream("some name").Open(QdbStreamMode.Open))
{
    stream.Read(myData, 0, myData.Length);
}

Inherits from Quasardb.QdbEntry

Public Functions

Stream Quasardb.QdbStream.Open(QdbStreamMode mode)

Opens the quasardb stream.

Return
A Stream with read, write and seek abilities.
Parameters
  • mode: Specifies how the stream must be opened
Exceptions
  • QdbAliasNotFoundException: The stream doesn’t exist in the database.
  • QdbResourceLockedException: The stream is locked by another client of the database.

Tag

class Quasardb::QdbTag

A tag in a quasardb database.

QdbTag can be constructed via QdbCluster.Tag.

How to tag a blob:

var cluster = new QdbCluster("qdb://127.0.0.1:2836");
cluster.Blob("some name").AttachTag("some tag");
Dim cluster = New QdbCluster("qdb://127.0.0.1:2836")
cluster.Blob("some name").AttachTag("some tag")
How to get tagged entries:
var cluster = New QdbCluster("qdb://127.0.0.1:2836");
IEnumerable<QdbEntry> tagged = cluster.Tag("some tag").GetEntries();
Dim cluster = New QdbCluster("qdb://127.0.0.1:2836")
Dim tagged = cluster.Tag("some tag").GetEntries()

See
QdbCluster, QdbEntry

Inherits from Quasardb.QdbEntry

Public Functions

IEnumerable<QdbEntry> Quasardb.QdbTag.GetEntries()

Gets database entries which are tagged with the current tag.

Return
A collection of entry.
See
QdbEntry

bool Quasardb.QdbTag.AttachEntry(QdbEntry entry)

Adds a tag to a database entry.

Return
true if the tag was added, false if the entry already had this tag.
Parameters
  • entry: The entry to add the tag to.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.
  • QdbIncompatibleTypeException: The tag’s alias conflicts with an existing entry.

bool Quasardb.QdbTag.AttachEntry(string entry)

Adds a tag to a database entry.

Return
true if the tag was added, false if the entry already had this tag.
Parameters
  • entry: The alias of the entry to add the tag to.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.
  • QdbIncompatibleTypeException: The tag’s alias conflicts with an existing entry.

bool Quasardb.QdbTag.HasEntry(QdbEntry entry)

Checks if an entry has this tag.

Return
true if the entry has this tag, false otherwise.
Parameters
  • entry: The entry to check.

bool Quasardb.QdbTag.HasEntry(string entry)

Checks if an entry has this tag.

Return
true if the entry has this tag, false otherwise.
Parameters
  • entry: The alias of the entry to check.

bool Quasardb.QdbTag.DetachEntry(QdbEntry entry)

Removes a tag from a database entry.

Return
true if the tag was removed, false if the entry didn’t have this tag.
Parameters
  • entry: The entry to remove the tag from.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.

bool Quasardb.QdbTag.DetachEntry(string entry)

Removes a tag from a database entry.

Return
true if the tag was removed, false if the entry didn’t have this tag.
Parameters
  • entry: The alias of the entry to remove the tag from.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.

Entry

class Quasardb::QdbEntry

An entry in a quasardb database.

Subclassed by Quasardb.QdbExpirableEntry, Quasardb.QdbStream, Quasardb.QdbTag, Quasardb.QdbUnknownEntry, Quasardb.TimeSeries.QdbTimeSeries

Public Functions

virtual bool Quasardb.QdbEntry.Remove()

Removes the entry from the database.

Return
true if the entry was removed, or false if the entry didn’t exist.

bool Quasardb.QdbEntry.AttachTag(QdbTag tag)

Adds a tag to the entry.

Return
true if the tag was added, false if the entry already had this tag.
See
QdbTag
Parameters
  • tag: The tag to add.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.
  • QdbIncompatibleTypeException: The tag’s alias conflicts with another entry.

bool Quasardb.QdbEntry.AttachTag(string tag)

Adds a tag to the entry.

Return
true if the tag was added, false if the entry already had this tag.
See
QdbTag
Parameters
  • tag: The alias of the tag.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.
  • QdbIncompatibleTypeException: The tag’s alias conflicts with another entry.

IEnumerable<QdbTag> Quasardb.QdbEntry.GetTags()

Gets the tags of the entry

Return
A collection of tag.
See
QdbTag
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.

bool Quasardb.QdbEntry.HasTag(QdbTag tag)

Checks if the entry has the specified tag.

Return
true if the entry has this tag, false otherwise.
See
QdbTag
Parameters
  • tag: The tag.

bool Quasardb.QdbEntry.HasTag(string tag)

Checks if the entry has the specified tag.

Return
true if the entry has this tag, false otherwise.
See
QdbTag
Parameters
  • tag: The alias of the tag.

bool Quasardb.QdbEntry.DetachTag(QdbTag tag)

Removes a tag from the entry.

Return
true if the entry had this tag, false if not.
See
QdbTag
Parameters
  • tag: The label of the tag.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.

bool Quasardb.QdbEntry.DetachTag(string tag)

Removes a tag from the entry.

Return
true if the entry had this tag, false if not.
See
QdbTag
Parameters
  • tag: The label of the tag.
Exceptions
  • QdbAliasNotFoundException: The entry doesn’t exists in the database.

Property

property Quasardb::QdbEntry::Alias

The alias of the entry in the database.

PrefixSelector

class Quasardb::QdbPrefixSelector

Selects entries by the beginning (ie prefix) of their alias.

Inherits from Quasardb.IQdbEntrySelector

Public Functions

Quasardb.QdbPrefixSelector.QdbPrefixSelector(string prefix, long maxCount)

Creates a selector with the specified prefix.

Parameters
  • prefix: The prefix that the aliases need to match.
  • maxCount: The maximum number of results.

SuffixSelector

class Quasardb::QdbSuffixSelector

Selects entries by the end (ie suffix) of their alias.

Inherits from Quasardb.IQdbEntrySelector

Public Functions

Quasardb.QdbSuffixSelector.QdbSuffixSelector(string suffix, long maxCount)

Creates a selector with the specified suffix.

Parameters
  • suffix: The suffix that the aliases need to match.
  • maxCount: The maximum number of results.

7.11.10. Version-History

The topics in this section describe the various changes made to the Quasardb API for .NET over the life of the project.

Version 2.1.0

This version requires quasardb server 2.1

Changes in the release:-

  1. Added support for time series.

Version 2.0.0

This version requires quasardb server 2.0

Changes in This Release:-

  1. Supports the following entry types:

    • blob
    • deque
    • hash set
    • integer
    • stream
    • tag
  2. Supports for batches.