lgraph_db

namespace lgraph
namespace lgraph_api

Functions

bool ShouldKillThisTask()

Determine if we should kill current task.

Returns

True if a KillTask command was issued for this task, either due to user request or timeout.

ThreadContextPtr GetThreadContext()

Gets thread context pointer, which can then be used in ShouldKillThisTask(ctx). Calling ShouldKillThisTask() is equivalent to ShouldKillThisTask(GetThreadContext()). In order to save the cost of GetThreadContext(), you can store the context and use it in ShouldKillThisTask(ctx).

Example: ```c++ ThreadContextPtr ctx = GetThreadContext(); while (HasMoreWorkToDo()) { if (ShouldKillThisTask(ctx)) { break; } DoWork(); } ```

Returns

The thread context.

bool ShouldKillThisTask(ThreadContextPtr ctx)

Determine if we should kill the task currently running in the thread identified by ctx.

Parameters

ctx – The context, as obtained with GetThreadContext.

Returns

True if a KillTask command was issued for this task.

Variables

const typedef void * ThreadContextPtr

Defines an alias representing the thread context pointer.

class GraphDB
#include <lgraph_db.h>

GraphDB represents a graph instance. In TuGraph, each graph instance has its own schema and access control settings. Accessing a GraphDB without appropriate access rights yields WriteNotAllowedError.

A GraphDB becomes invalid if Close() is called, in which case all transactions and iterators associated with that GraphDB become invalid. Further operation on that GraphDB yields InvalidGraphDBError.

Public Functions

explicit GraphDB(lgraph::AccessControlledDB *db_with_access_control, bool read_only, bool owns_db = false)

For internal use only. Users should use Galaxy::OpenGraph() to get GraphDB.

GraphDB(GraphDB&&)
GraphDB &operator=(GraphDB&&)
~GraphDB()
void Close()

Close the graph. This will close the graph and release all transactions, iterators associated with the graph. After calling Close(), the graph becomes invalid, and cannot be used anymore.

Transaction CreateReadTxn()

Creates a read transaction.

Throws

InvalidGraphDBError – Thrown when currently GraphDB is invalid.

Returns

The new read transaction.

Transaction CreateWriteTxn(bool optimistic = false)

Creates a write transaction. Write operations can only be performed in write transactions, otherwise exceptions will be thrown. A write transaction can be optimistic. Optimistic transactions can run in parallel and any conflict will be detected during commit. If a transaction conflicts with an ealier one, a TxnConflictError will be thrown during commit.

Throws
Parameters

optimistic – (Optional) True to create an optimistic transaction.

Returns

The new write transaction.

Transaction ForkTxn(Transaction &txn)

Forks a read transaction. The resulting read transaction will share the same view as the forked one, meaning that when reads are performed on the same vertex/edge, the results will always be identical, whether they are performed in the original transaction or the forked one. Only read transactions can be forked. Calling ForkTxn() on a write txn causes an InvalidForkError to be thrown.

Throws
Parameters

txn – [in] The read transaction to be forked.

Returns

A new read Transaction that shares the same view with txn.

void Flush()

Flushes buffered data to disk. If there have been some async transactions, there could be data that are written to this graph, but not persisted to disk yet. Calling Flush() will persist the data and prevent data loss in case of system crash.

Throws

InvalidGraphDBError – Thrown when currently GraphDB is invalid.

void DropAllData()

Drop all the data in the graph, including labels, indexes and vertexes/edges..

Throws
void DropAllVertex()

Drop all vertex and edges but keep the labels and indexes.

Throws
size_t EstimateNumVertices()

Estimate number of vertices. We don’t maintain the exact number of vertices, but only the next vid. This function actually returns the next vid to be used. So if you have deleted a lot of vertices, the result can be quite different from actual number of vertices.

Throws

InvalidGraphDBError – Thrown when currently GraphDB is invalid.

Returns

Estimated number of vertices.

bool AddVertexLabel(const std::string &label, const std::vector<FieldSpec> &fds, const VertexOptions &options)

Adds a vertex label.

Throws
Parameters

  • label – The label name.

  • fds – The field specifications.

  • primary_field – The primary field.

Returns

True if it succeeds, false if the label already exists.

bool DeleteVertexLabel(const std::string &label, size_t *n_modified = nullptr)

Deletes a vertex label and all the vertices with this label.

Throws
Parameters

  • label – The label name.

  • n_modified – [out] (Optional) If non-null, return the number of deleted vertices.

Returns

True if it succeeds, false if the label does not exist.

bool AlterVertexLabelDelFields(const std::string &label, const std::vector<std::string> &del_fields, size_t *n_modified = nullptr)

Deletes fields in a vertex label. This function also updates the vertex data and indices accordingly to make sure the database remains in consistent state.

Throws
Parameters

  • label – The label name.

  • del_fields – Labels of the fields to be deleted.

  • n_modified – [out] (Optional) If non-null, return the number of modified vertices.

Returns

True if it succeeds, false if the label does not exist.

bool AlterVertexLabelAddFields(const std::string &label, const std::vector<FieldSpec> &add_fields, const std::vector<FieldData> &default_values, size_t *n_modified = nullptr)

Add fields to a vertex label. The new fields in existing vertices will be filled with default values.

Throws
Parameters

  • label – The label name.

  • add_fields – The add fields.

  • default_values – The default values of the newly added fields.

  • n_modified – [out] (Optional) If non-null, return the number of modified vertices.

Returns

True if it succeeds, false if the label does not exist.

bool AlterVertexLabelModFields(const std::string &label, const std::vector<FieldSpec> &mod_fields, size_t *n_modified = nullptr)

Modify fields in a vertex label, either chage the data type or optional, or both.

Throws
Parameters

  • label – The label name.

  • mod_fields – The new specification of the modified fields.

  • n_modified – [out] (Optional) If non-null, return the number of modified vertices.

Returns

True if it succeeds, false if the label does not exist.

bool AddEdgeLabel(const std::string &label, const std::vector<FieldSpec> &fds, const EdgeOptions &options)

Add a edge label, specifying its schema. It is allowed to specify edge constrains, too. An edge can be bound to several (source_label, destination_label) pairs, which makes sure this type of edges will only be added between these types of vertices. By default, the constain is empty, meaning that the edge is not restricted.

Throws
Parameters

  • label – The label name.

  • fds – The field specifications.

  • temporal_field – The temporal field for tid.

  • edge_constraints – (Optional) The edge constraints. An empty constrain means no restriction.

Returns

True if it succeeds, false if label already exists.

bool DeleteEdgeLabel(const std::string &label, size_t *n_modified = nullptr)

Deletes an edge label and all the edges of this type.

Throws
Parameters

  • label – The label.

  • n_modified – [out] (Optional) If non-null, return the number of deleted edges.

Returns

True if it succeeds, false if label does not exist.

bool AlterLabelModEdgeConstraints(const std::string &label, const std::vector<std::pair<std::string, std::string>> &constraints)

Modify edge constraint. Existing edges that violate the new constrain will be removed.

Throws
Parameters

  • label – The label name.

  • constraints – The new edge constraint.

Returns

True if it succeeds, false if the edge label does not exist.

bool AlterEdgeLabelDelFields(const std::string &label, const std::vector<std::string> &del_fields, size_t *n_modified = nullptr)

Deletes fields in an edge label.

Throws
Parameters

  • label – The label name.

  • del_fields – The fields to be deleted.

  • n_modified – [out] (Optional) If non-null, return the number of edges modified.

Returns

True if it succeeds, false if it fails.

bool AlterEdgeLabelAddFields(const std::string &label, const std::vector<FieldSpec> &add_fields, const std::vector<FieldData> &default_values, size_t *n_modified = nullptr)

Add fields to an edge label. The new fields in existing edges will be set to default values.

Throws
Parameters

  • label – The label name.

  • add_fields – The fields to add.

  • default_values – The default values.

  • n_modified – [inout] (Optional) If non-null, return the number of modified edges.

Returns

True if it succeeds, false if the edge label does not exist.

bool AlterEdgeLabelModFields(const std::string &label, const std::vector<FieldSpec> &mod_fields, size_t *n_modified = nullptr)

Modify fields in an edge label. Data type and OPTIONAL can be modified.

Throws
Parameters

  • label – The label name.

  • mod_fields – The modifier fields.

  • n_modified – [inout] (Optional) If non-null, return the number of modified edges.

Returns

True if it succeeds, false if the label does not exist.

bool AddVertexIndex(const std::string &label, const std::string &field, bool is_unique)

Adds an index to ‘label:field’. This function blocks until the index is fully created.

Throws
Parameters

  • label – The label name.

  • field – The field name.

  • is_unique – True if is unique index, false if not.

Returns

True if it succeeds, false if the index already exists.

bool AddEdgeIndex(const std::string &label, const std::string &field, bool is_unique)

Adds an index to ‘label:field’. This function blocks until the index is fully created.

Throws
Parameters

  • label – The label.

  • field – The field.

  • is_unique – True if the field content is unique for each vertex.

Returns

True if it succeeds, false if the index already exists.

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

Check if this vertex_label:field is indexed.

Throws
Parameters

  • label – The label.

  • field – The field.

Returns

True if index exists, false if label:field exists but not indexed.

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

Check if this edge_label:field is indexed.

Throws
Parameters

  • label – The label.

  • field – The field.

Returns

True if index exists, false if label:field exists but not indexed.

bool DeleteVertexIndex(const std::string &label, const std::string &field)

Deletes the index to ‘vertex_label:field’.

Throws
Parameters

  • label – The label.

  • field – The field.

Returns

True if it succeeds, false if the index does not exists.

bool DeleteEdgeIndex(const std::string &label, const std::string &field)

Deletes the index to ‘edge_label:field’.

Throws
Parameters

  • label – The label.

  • field – The field.

Returns

True if it succeeds, false if the index does not exists.

std::string GetDescription() const

Get graph description.

Throws

InvalidGraphDBError – Thrown when currently GraphDB is invalid.

Returns

The description.

size_t GetMaxSize() const

Get maximum graph size.

Throws

InvalidGraphDBError – Thrown when currently GraphDB is invalid.

Returns

The maximum size.

bool AddVertexFullTextIndex(const std::string &vertex_label, const std::string &field)

Add fulltext index to ‘vertex_label:field’.

Throws
Parameters

  • vertex_label – The vertex label.

  • field – The field.

Returns

True if it succeeds, false if the fulltext index already exists.

bool AddEdgeFullTextIndex(const std::string &edge_label, const std::string &field)

Add fulltext index to ‘edge_label:field’.

Throws
Parameters

  • edge_label – The edge label.

  • field – The field.

Returns

True if it succeeds, false if the fulltext index already exists.

bool DeleteVertexFullTextIndex(const std::string &vertex_label, const std::string &field)

Delete the fulltext index of ‘vertex_label:field’.

Throws
Parameters

  • vertex_label – The vertex label.

  • field – The field.

Returns

True if it succeeds, false if the fulltext index does not exists.

bool DeleteEdgeFullTextIndex(const std::string &edge_label, const std::string &field)

Delete the fulltext index of ‘edge_label:field’.

Throws
Parameters

  • edge_label – The edge label.

  • field – The field.

Returns

True if it succeeds, false if the fulltext index does not exists.

void RebuildFullTextIndex(const std::set<std::string> &vertex_labels, const std::set<std::string> &edge_labels)

Rebuild the fulltext index of vertex_labels and edge_labels.

Parameters

  • vertex_labels – The vertex labels whose fulltext index need to rebuild.

  • edge_labels – The edge labels whose fulltext index need to rebuild.

std::vector<std::tuple<bool, std::string, std::string>> ListFullTextIndexes()

List fulltext indexes of vertex and edge.

Throws
Returns

Format of returned data : (is_vertex, label_name, property_name)

std::vector<std::pair<int64_t, float>> QueryVertexByFullTextIndex(const std::string &label, const std::string &query, int top_n)

Query vertex by fulltext index.

Throws
Parameters

  • label – The vertex label.

  • query – Lucene query language.

  • top_n – return top n data.

Returns

Vertex vids and score. Throws exception on error.

std::vector<std::pair<EdgeUid, float>> QueryEdgeByFullTextIndex(const std::string &label, const std::string &query, int top_n)

Query edge by fulltext index.

Throws
Parameters

  • label – The edge label.

  • query – Lucene query language.

  • top_n – return top n data.

Returns

Edge uids and score. Throws exception on error.

void RefreshCount()

Recount the total number of vertex and edge, stop writing during the count.

Throws

Private Functions

GraphDB(const GraphDB&) = delete

Copying is disabled.

GraphDB &operator=(const GraphDB&) = delete

Private Members

lgraph::AccessControlledDB *db_
bool should_delete_db_ = false
bool read_only_ = false