lgraph_txn

namespace lgraph

namespace lgraph_api

class Transaction

#include <lgraph_txn.h>

TuGraph operations happen in transactions. A transaction is sequence of operations that is carried out atomically on the GraphDB. TuGraph transactions provides full ACID guarantees.

Transactions are created using GraphDB::CreateReadTxn() and GraphDB::CreateWriteTxn(). A read transaction can only perform read operations, otherwise an exception is thrown. A write transaction can perform reads as well as writes. There are performance differences between read and write operations. So if you only need read in a transaction, you should create a read transaction.

Each transaction must be used in one thread only, and they should not be passed from one thread to another unless it is a forked transaction.

Read transactions can be forked. The new copy of the transaction will have the same view as the forked one, and it can be used in a separate thread. By forking from one read transaction and using the forked copies in different threads, we can parallelize the execution of specific operations. For example, you can implement a parallel BFS with this capability. Also, you can dump a snapshot of the whole graph using

Public Functions

Transaction(Transaction &&rhs) = default

Transaction &operator=(Transaction &&rhs) = default

Transaction(const Transaction&) = delete

Transaction &operator=(const Transaction&) = delete

void Commit(): Commits this transaction. Note that optimistic write transactions may fail to commit (an TxnConflictError would be thrown).

void Abort(): Aborts this transaction.

bool IsValid() const

Query if this transaction is valid. Transaction becomes invalid after calling Abort() or Commit(). Operations on invalid transaction yields exceptions.

Returns: True if valid, false if not.

bool IsReadOnly() const

Query if this txn is read only.

Returns: True if read only, false if not.

const std::shared_ptr<lgraph::Transaction> GetTxn()

Get Transaction.

Returns: Transaction

VertexIterator GetVertexIterator()

Get a vertex iterator pointing to the first vertex. If there is no vertex, the iterator is invalid.

Returns: The vertex iterator.

VertexIterator GetVertexIterator(int64_t vid, bool nearest = false)

Gets a vertex iterator pointing to the Vertex with vid. If the vertex does not exist, the iterator is invalid. If nearest==true, the iterator points to the first vertex sorted by vid, with id>=vid.

Parameters

vid – The vid.
nearest – (Optional) True to point to the nearest vertex sorted by vid.

Returns

The vertex iterator.

OutEdgeIterator GetOutEdgeIterator(const EdgeUid &euid, bool nearest = false)

Gets an out edge iterator pointing to the edge specified by euid. If nearest==true, and the specified edge does not exist, return the first edge that sorts after the specified one.

Parameters

euid – Edge Unique Id.
nearest – (Optional) If true, get the first edge that sorts after the specified one if the specified one does not exist.

Returns

The out edge iterator.

OutEdgeIterator GetOutEdgeIterator(const int64_t src, const int64_t dst, const int16_t lid)

InEdgeIterator GetInEdgeIterator(const EdgeUid &euid, bool nearest = false)

Gets an in edge iterator pointing to the edge specified by euid. If nearest==true, and the specified edge does not exist, return the first edge that sorts after the specified one.

Parameters

euid – Edge Unique Id.
nearest – (Optional) If true, get the first edge that sorts after the specified one if the specified one does not exist.

Returns

The out edge iterator.

InEdgeIterator GetInEdgeIterator(const int64_t src, const int64_t dst, const int16_t lid)

size_t GetNumVertexLabels()

Gets number of vertex labels.

Returns: The number of vertex labels.

size_t GetNumEdgeLabels()

Gets number of edge labels.

Returns: The number of edge labels.

std::vector<std::string> ListVertexLabels()

Lists all vertex labels.

Returns: Label names.

std::vector<std::string> ListEdgeLabels()

List all edge labels.

Returns: Label names.

size_t GetVertexLabelId(const std::string &label)

Gets vertex label id corresponding to the label name.

Parameters: label – The label name.
Returns: The label id.

size_t GetEdgeLabelId(const std::string &label)

Gets edge label id corresponding to the label name.

Parameters: label – The label.
Returns: The edge label id.

std::vector<FieldSpec> GetVertexSchema(const std::string &label)

Gets edge schema definition corresponding to the vertex label.

Parameters: label – The label.
Returns: The schema.

std::vector<FieldSpec> GetEdgeSchema(const std::string &label)

Gets edge schema definition corresponding to the edge label.

Parameters: label – The label.
Returns: The edge schema.

size_t GetVertexFieldId(size_t label_id, const std::string &field_name)

Gets vertex field id.

Parameters

label_id – Identifier for the label.
field_name – Field name.

Returns

The vertex field identifiers.

std::vector<size_t> GetVertexFieldIds(size_t label_id, const std::vector<std::string> &field_names)

Gets vertex field ids.

Parameters

label_id – Identifier for the label.
field_names – Field names.

Returns

The vertex field identifiers.

size_t GetEdgeFieldId(size_t label_id, const std::string &field_name)

Gets edge field id.

Parameters

label_id – Identifier for the label.
field_name – Field name.

Returns

The edge field identifier.

std::vector<size_t> GetEdgeFieldIds(size_t label_id, const std::vector<std::string> &field_names)

Gets edge field ids.

Parameters

label_id – Identifier for the label.
field_names – Field names.

Returns

The edge field identifier.

int64_t AddVertex(const std::string &label_name, const std::vector<std::string> &field_names, const std::vector<std::string> &field_value_strings)

Adds a vertex. All non-nullable fields must be specified. VertexIndex is also updated. If a unique_id is indexed for the vertex, and the same unique_id exists, an exception is thrown.

Parameters

label_name – Name of the label.
field_names – List of names of the fields.
field_value_strings – The field values in string representation.

Returns

Vertex id of the new vertex.

int64_t AddVertex(const std::string &label_name, const std::vector<std::string> &field_names, const std::vector<FieldData> &field_values)

Adds a vertex. All non-nullable fields must be specified. VertexIndex is also updated. If a unique_id is indexed for the vertex, and the same unique_id exists, an exception is thrown.

Parameters

label_name – Name of the label.
field_names – List of names of the fields.
field_values – The field values.

Returns

Vertex id of the new vertex.

int64_t AddVertex(size_t label_id, const std::vector<size_t> &field_ids, const std::vector<FieldData> &field_values)

Adds a vertex. All non-nullable fields must be specified. VertexIndex is also updated. If a unique_id is indexed for the vertex, and the same unique_id exists, an exception is thrown.

Parameters

label_id – Label id.
field_ids – List of field ids.
field_values – The field values.

Returns

Vertex id of the new vertex.

EdgeUid AddEdge(int64_t src, int64_t dst, const std::string &label, const std::vector<std::string> &field_names, const std::vector<std::string> &field_value_strings)

Adds an edge. All non-nullable fields must be specified. An exception is thrown if src or dst does not exist.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label – The label name.
field_names – List of field names.
field_value_strings – List of field values in string representation.

Returns

EdgeUid of the new edge.

EdgeUid AddEdge(int64_t src, int64_t dst, const std::string &label, const std::vector<std::string> &field_names, const std::vector<FieldData> &field_values)

Adds an edge. All non-nullable fields must be specified. An exception is thrown if src or dst does not exist.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label – The label name.
field_names – List of field names.
field_values – List of field values.

Returns

EdgeUid of the new edge.

EdgeUid AddEdge(int64_t src, int64_t dst, size_t label_id, const std::vector<size_t> &field_ids, const std::vector<FieldData> &field_values)

Adds an edge. All non-nullable fields must be specified. An exception is thrown if src or dst does not exist.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label_id – The label id.
field_ids – List of field ids.
field_values – List of field values.

Returns

EdgeUid of the new edge.

bool UpsertEdge(int64_t src, int64_t dst, const std::string &label, const std::vector<std::string> &field_names, const std::vector<std::string> &field_value_strings)

Upsert edge. If there is no src->dst edge, insert it. Otherwise, try to update the edge’s property. If the edge exists and the label differs from specified label, an exception is thrown.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label – The label name.
field_names – List of field names.
field_value_strings – List of field values in string representation.

Returns

True if the edge is inserted, false if the edge is updated.

bool UpsertEdge(int64_t src, int64_t dst, const std::string &label, const std::vector<std::string> &field_names, const std::vector<FieldData> &field_values)

Upsert edge. If there is no src->dst edge, insert it. Otherwise, try to update the edge’s property. If the edge exists and the label differs from specified label, an exception is thrown.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label – The label name.
field_names – List of field names.
field_values – List of field values.

Returns

True if the edge is inserted, false if the edge is updated.

bool UpsertEdge(int64_t src, int64_t dst, size_t label_id, const std::vector<size_t> &field_ids, const std::vector<FieldData> &field_values)

Upsert edge. If there is no src->dst edge, insert it. Otherwise, try to update the edge’s property. If the edge exists and the label differs from specified label, an exception is thrown.

Parameters

src – Source vertex id.
dst – Destination vertex id.
label_id – The label id.
field_ids – List of field ids.
field_values – List of field values.

Returns

True if the edge is inserted, false if the edge is updated.

std::vector<IndexSpec> ListVertexIndexes()

List indexes.

Returns: A vector of vertex index specs.

std::vector<IndexSpec> ListEdgeIndexes()

List indexes.

Returns: A vector of edge index specs.

VertexIndexIterator GetVertexIndexIterator(size_t label_id, size_t field_id, const FieldData &key_start, const FieldData &key_end)

Gets vertex index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all vertexes that has field value v.

Parameters

label_id – The label id.
field_id – The field id.
key_start – The key start.
key_end – The key end, inclusive.

Returns

The index iterator.

EdgeIndexIterator GetEdgeIndexIterator(size_t label_id, size_t field_id, const FieldData &key_start, const FieldData &key_end)

Gets edge index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all edges that has field value v.

Parameters

label_id – The label id.
field_id – The field id.
key_start – The key start.
key_end – The key end, inclusive.

Returns

The index iterator.

VertexIndexIterator GetVertexIndexIterator(const std::string &label, const std::string &field, const FieldData &key_start, const FieldData &key_end)

Gets vertex index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all vertexes that has field value v.

Parameters

label – The label.
field – The field.
key_start – The key start.
key_end – The key end, inclusive.

Returns

The index iterator.

EdgeIndexIterator GetEdgeIndexIterator(const std::string &label, const std::string &field, const FieldData &key_start, const FieldData &key_end)

Gets index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all edges that has field value v.

Parameters

label – The label.
field – The field.
key_start – The key start.
key_end – The key end, inclusive.

Returns

The index iterator.

VertexIndexIterator GetVertexIndexIterator(const std::string &label, const std::string &field, const std::string &key_start, const std::string &key_end)

Gets index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all vertexes that has field value v.

Parameters

label – The label.
field – The field.
key_start – The key start.
key_end – The key end.

Returns

The index iterator.

EdgeIndexIterator GetEdgeIndexIterator(const std::string &label, const std::string &field, const std::string &key_start, const std::string &key_end)

Gets index iterator. The iterator has field value [key_start, key_end]. So key_start=key_end=v returns an iterator pointing to all edges that has field value v.

Parameters

label – The label.
field – The field.
key_start – The key start.
key_end – The key end.

Returns

The index iterator.

bool IsVertexIndexed(const std::string &label, const std::string &field)

Query if index is ready for use. This should be used only to decide whether to use an index. To wait for an index to be ready, use lgraphDB::WaitIndexReady().

VertexIndex building is async, especially when added for a (label, field) that already has a lot of vertices. This function tells us if the index building is finished.

DO NOT wait for index building in a transaction. Write transactions block other write transactions, so blocking in a write transaction is always a bad idea. And long-living read transactions interfere with GC, making the DB grow unexpectly.

Parameters

label – The label.
field – The field.

Returns

True if index ready, false if not.

bool IsEdgeIndexed(const std::string &label, const std::string &field)

Query if index is ready for use. This should be used only to decide whether to use an index. To wait for an index to be ready, use lgraphDB::WaitIndexReady().

VertexIndex building is async, especially when added for a (label, field) that already has a lot of edges. This function tells us if the index building is finished.

DO NOT wait for index building in a transaction. Write transactions block other write transactions, so blocking in a write transaction is always a bad idea. And long-living read transactions interfere with GC, making the DB grow unexpectly.

Parameters

label – The label.
field – The field.

Returns

True if index ready, false if not.

VertexIterator GetVertexByUniqueIndex(const std::string &label_name, const std::string &field_name, const std::string &field_value_string)

Gets vertex by unique index. Throws exception if there is no such vertex.

Parameters

label_name – Name of the label.
field_name – Name of the field.
field_value_string – The field value string.

Returns

The vertex by unique index.

OutEdgeIterator GetEdgeByUniqueIndex(const std::string &label_name, const std::string &field_name, const std::string &field_value_string)

Gets edge by unique index. Throws exception if there is no such vertex.

Parameters

label_name – Name of the label.
field_name – Name of the field.
field_value_string – The field value string.

Returns

The vertex by unique index.

VertexIterator GetVertexByUniqueIndex(const std::string &label_name, const std::string &field_name, const FieldData &field_value)

Gets vertex by unique index. Throws exception if there is no such vertex.

Parameters

label_name – Name of the label.
field_name – Name of the field.
field_value – The field value.

Returns

The vertex by unique index.

OutEdgeIterator GetEdgeByUniqueIndex(const std::string &label_name, const std::string &field_name, const FieldData &field_value)

Gets edge by unique index. Throws exception if there is no such vertex.

Parameters

label_name – Name of the label.
field_name – Name of the field.
field_value – The field value.

Returns

The vertex by unique index.

VertexIterator GetVertexByUniqueIndex(size_t label_id, size_t field_id, const FieldData &field_value)

Gets vertex by unique index. Throws exception if there is no such vertex.

Parameters

label_id – Identifier for the label.
field_id – Identifier for the field.
field_value – The field value.

Returns

The vertex by unique index.

OutEdgeIterator GetEdgeByUniqueIndex(size_t label_id, size_t field_id, const FieldData &field_value)

Gets edge by unique index. Throws exception if there is no such vertex.

Parameters

label_id – Identifier for the label.
field_id – Identifier for the field.
field_value – The field value.

Returns

The vertex by unique index.

size_t GetNumVertices()

Gets the number of vertices.

Returns: The nubmer of vertices.

const std::string &GetVertexPrimaryField(const std::string &label)

Gets vertex primary field.

Returns: The primary field.

std::pair<uint64_t, uint64_t> Count()

Get the total number of vertex and edge.

Returns: std::pair object, first element is vertex number, second is edge number.

std::vector<std::tuple<bool, std::string, int64_t>> CountDetail()

Get the total number of vertex or edge for each label.

Returns: std::tuple object list, first element indicates whether it is VERTEX or EDGE, second is label name, third is number.

Private Functions

explicit Transaction(lgraph::Transaction&&)

Private Members

std::shared_ptr<lgraph::Transaction> txn_

Friends

friend class GraphDB