Create

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Jump to the Code block for a combined complete example.

Setup

The following examples will use the setup and record structure below to illustrate single record creation in an Aerospike database.

using Aerospike.Client;
using System;
using System.Collections;

// Define host configuration
Host config = new Host("127.0.0.1", 3000);
// Establishes a connection to the server
AerospikeClient client = new AerospikeClient(null, config);

The record structure:

Occurred: Integer
Reported: Integer
Posted: Integer
Report: Map
{
    shape: List,
    summary: String,
    city: String,
    state: String,
    duration: String
}
Location: GeoJSON

Policies

Write policies define additional semantics for the write operation. Instead of using the default write policies, we can set them on a per command basis.

The following example creates a new write policy container object that sets the send key policy to true. This stores the user defined key with the record, and returns it with read commands.

// Create new write policy
WritePolicy writePolicy = new WritePolicy();
writePolicy.sendKey = true;

Record expiration

WritePolicy.expiration controls the record’s time-to-live. Leaving it at the default of 0 is easy to misread: it does not mean “never expire,” it means “use the namespace default-ttl.” If that namespace has a finite default-ttl, records written with the default policy expire.

`expiration`	Meaning
`0`	Use the namespace `default-ttl`.
`-1`	Never expire. Requires server 3.1.4 or later.
`-2`	Leave the existing record’s TTL unchanged. Requires server 3.10.1 or later.
positive	TTL in seconds from now.

Key

The key is a tuple made up of: (namespace, set, user defined key).

The following example creates a key using the sandbox namespace, ufodata set, and user defined key 5001.

// Create the record key
Key key = new Key("sandbox", "ufodata", 5001);

A user defined key must be a string, integer, or byte array. Passing a list, map, boolean, GeoJSON value, or Value.AsNull to the Key constructor throws AerospikeException with ResultCode.PARAMETER_ERROR before any command reaches the server.

Create-only writes

Despite this page’s title, Put() is create-or-update. Its default RecordExistsAction.UPDATE merges the supplied bins into an existing record, and bins that a later write does not name are left in place.

Key key = new(ns, set, MergeKey);
WritePolicy policy = new(writePolicy)
{
  sendKey = true
};

client.Put(policy, key, new Bin("name", "Ada"), new Bin("language", "C#"));

// UPDATE is the default RecordExistsAction. Only the supplied bin is changed,
// so the existing "language" bin remains in the record.
client.Put(policy, key, new Bin("name", "Grace"));

To reject the write when the record already exists, copy the default policy and set RecordExistsAction.CREATE_ONLY. The server then returns KEY_EXISTS_ERROR instead of merging. Copying rather than mutating the shared default keeps concurrent commands unaffected.

Catch that duplicate case on its own. Oversized bin values or records, bin names over the 15-character limit, and unavailable partitions all arrive as AerospikeException too, so a bare catch would silently report them as duplicates.

Key key = new(ns, set, CreateKey);

WritePolicy createPolicy = new(writePolicy)
{
  sendKey = true,
  recordExistsAction = RecordExistsAction.CREATE_ONLY,
  // Positive values are TTL seconds. 0 uses the namespace default-ttl,
  // -1 never expires, and -2 leaves an existing TTL unchanged.
  expiration = 60
};

try
{
  client.Put(createPolicy, key, new Bin("status", "new"));
}
catch (AerospikeException ae) when (ae.Result == ResultCode.KEY_EXISTS_ERROR)
{
  Console.WriteLine("The record was already created.");
}
catch (AerospikeException ae)
{
  Console.Error.WriteLine($"Create failed: {ResultCode.GetResultString(ae.Result)}");
  throw;
}

Create a record

A record is the basic unit of storage in the database. A record is composed of: (key, metadata, bins).

Setup

Expand the block below to see the creation of the variables used in the write example below.

View the data creation

// Create a list of shapes to add to the report map
List<string> shape = new List<string>();
shape.Add("circle");
shape.Add("flash");
shape.Add("disc");

// Create the report map
Dictionary<string, object> reportMap = new Dictionary<string, object>();
reportMap.Add("city", "Ann Arbor");
reportMap.Add("state", "Michigan");
reportMap.Add("shape", shape);
reportMap.Add("duration", "5 minutes");
reportMap.Add("summary", "Large flying disc flashed in the sky above the student union. Craziest thing I've ever seen!");

// Format coordinates as a GeoJSON string
String geoLoc = "{\"type\":\"Point\", \"coordinates\":[42.2808,83.7430]}";

Write

The following example shows the creation of the bins and the writing of the record to the database.

// Create the bins as Bin("binName", value)
Bin occurred = new Bin("occurred", 20220531);
Bin reported = new Bin("reported", 20220601);
Bin posted = new Bin("posted", 20220601);
// reportMap defined in the section above
Bin report = new Bin("report", reportMap);
// geoLoc defined in the section above
Bin location = new Bin("location", Value.GetAsGeoJSON(geoLoc));

// Write the record to Aerospike
client.Put(writePolicy, key, occurred, reported, posted, report, location);

// Close the connection to the server
client.Close();

Code block

Expand this section for a single code block to create a record

using Aerospike.Client;
using System;
using System.Collections;

// Define host configuration
Host config = new Host("127.0.0.1", 3000);
// Establishes a connection to the server
AerospikeClient client = new AerospikeClient(null, config);

// Create new write policy
WritePolicy writePolicy = new WritePolicy();
writePolicy.sendKey = true;

// Create the record key
Key key = new Key("sandbox", "ufodata", 5001);

// Create a list of shapes to add to the report map
List<string> shape = new List<string>();
shape.Add("circle");
shape.Add("flash");
shape.Add("disc");

// Create the report map
Dictionary<string, object> reportMap = new Dictionary<string, object>();
reportMap.Add("city", "Ann Arbor");
reportMap.Add("state", "Michigan");
reportMap.Add("shape", shape);
reportMap.Add("duration", "5 minutes");
reportMap.Add("summary", "Large flying disc flashed in the sky above the student union. Craziest thing I've ever seen!");

// Format coordinates as a GeoJSON string
String geoLoc = "{\"type\":\"Point\", \"coordinates\":[42.2808,83.7430]}";

// Create the bins as Bin("binName", value)
Bin occurred = new Bin("occurred", 20220531);
Bin reported = new Bin("reported", 20220601);
Bin posted = new Bin("posted", 20220601);
// reportMap defined in the section above
Bin report = new Bin("report", reportMap);
// geoLoc defined in the section above
Bin location = new Bin("location", Value.GetAsGeoJSON(geoLoc));

// Write the record to Aerospike
client.Put(writePolicy, key, occurred, reported, posted, report, location);

// Close the connection to the server
client.Close();