/// <summary>
/// Upsert (Insert or Update) multiple edges into the database using a TPL Dataflow block.
/// This call uses the SQL API to upsert the edges as a document.
/// </summary>
/// <param name="edges">Edges to upsert</param>
/// <param name="reportingCallback">[Optional] Method to be called based on the <paramref name="reportingInterval"/>. Generally used to provide a progress update to callers. Defaults to null./></param>
/// <param name="reportingInterval">[Optional] interval in seconds to to call the reporting callback. Defaults to 10s</param>
/// <param name="threads">[Optional] Number of threads to use for the paralel execution. Defaults to 4</param>
/// <param name="cancellationToken">Cancellation token to cancel the operation</param>
/// <exception cref="InvalidOperationException">Throws invalid operation exception if the GraphClient was initialized without a <see cref="CosmosClientSql"/>.</exception>
/// <example>
/// <![CDATA[
/// await _client.UpsertVertex(elements, (partial) => { Console.WriteLine($"upserted {partial.Count()} vertices");
/// ]]>
/// </example>
/// <returns><see cref="CosmosResponse"/> that tracks success status along with various performance parameters.</returns>
public Task <IEnumerable <CosmosResponse> > UpsertEdges(IEnumerable <EdgeDefinition> edges, Action <IEnumerable <CosmosResponse> > reportingCallback = null, TimeSpan?reportingInterval = null, int threads = 4, CancellationToken cancellationToken = default(CancellationToken))
{
EnsureCosmosSqlClient();
//Could've used InsertVertex instead of the lambda, but I don't want to the EnsureCosmosClient() for every call
return(CosmosSqlClient.ProcessMultipleDocuments(edges, (EdgeDefinition edgeDef) => { return CosmosSqlClient.UpsertDocumentInternal(CosmosSerializer.ToGraphEdge(edgeDef.EdgeEntity, edgeDef.SourceVertex, edgeDef.TargetVertex, edgeDef.Single)); }, reportingCallback, reportingInterval, threads, cancellationToken));
}
/// <summary>
/// Execute a SQL statement against the graph database.
/// Forward the request to the SQL Client with a JObject type and then convert the resulting graphson documents into our entity using the serialization helper.
/// </summary>
/// <param name="query">Query to execute</param>
/// <param name="pagedResults">true to return only one page of the result set, false(Default) to return all results. </param>
/// <param name="continuationToken">token to pass into the query iterator to resume from a specific page. Should be present when using pageResults = true</param>
/// <param name="cancellationToken">cancellatinToken used to cancel an operation in progress.</param>
/// <returns><see cref="CosmosResponse"/> that encapsulates the result of the query and tracks success status along with various performance parameters.</returns>
public async Task <CosmosResponse <IEnumerable <T> > > ExecuteSQL <T>(string query, bool pagedResults = false, string continuationToken = "", CancellationToken cancellationToken = default(CancellationToken))
{
EnsureCosmosSqlClient();
if (CosmosEntitySerializer.IsTypeDirectlySerializableToGraph(typeof(T)))
{
return(await CosmosSqlClient.ExecuteSQL <T>(query, pagedResults, continuationToken, cancellationToken));
}
var res = await CosmosSqlClient.ExecuteSQL <JObject>(query, pagedResults, continuationToken, cancellationToken);
var cosmosResult = res.Clone <IEnumerable <T> >();
if (typeof(T) == typeof(JObject) || typeof(T) == typeof(object))
{
return(cosmosResult);
}
if (!res.IsSuccessful)
{
return(cosmosResult);
}
cosmosResult.Result = res.Result.Select(CosmosSerializer.FromGraphson <T>).ToArray();
return(cosmosResult);
}
/// <summary>
/// Read a graph vertex using the SQL API.
/// Forward the request to the SQL Client with a JObject type and then convert the resulting graphson document into our entity using the serialization helper.
/// </summary>
/// <returns><see cref="CosmosResponse"/> that encapsulates the result of the query and tracks success status along with various performance parameters.</returns>
public async Task <CosmosResponse <T> > ReadVertex <T>(string docId, string partitionKey)
{
EnsureCosmosSqlClient();
var res = await CosmosSqlClient.ReadDocument <JObject>(docId, partitionKey);
var cosmosResult = res.Clone <T>();
if (!res.IsSuccessful)
{
return(cosmosResult);
}
cosmosResult.Result = CosmosSerializer.FromGraphson <T>(res.Result);
return(cosmosResult);
}
/// <summary>
/// Upsert an edge into the database by referencing the source and target vertices just by their base properties (id, partitionKey, label).
/// This call uses the SQL API to upsert the edge as a document.
/// </summary>
/// <param name="edge">Edge entity to upsert</param>
/// <param name="source">Source vertex of the edge</param>
/// <param name="target">Target vertex of the edge</param>
/// <param name="single">
/// [Optional] Indicates if there can only be one edge of this kind between the 2 vertices. Defaults to false.
/// i.e an edge defining a 'isFriend' relationship between 2 people needs to be singe:true because only one friend edge makes sense.
/// i.e an edge defining a 'visited' relationship between a person and a restaurant needs to be single:false because a person can visit the restaurant multiple times
/// </param>
/// <exception cref="InvalidOperationException">Throws invalid operation exception if the GraphClient was initialized without a CosmosSQLClient</exception>
/// <returns><see cref="CosmosResponse"/> that tracks success status along with various performance parameters</returns>
public Task <CosmosResponse> UpsertEdge <T>(T edge, GraphItemBase source, GraphItemBase target, bool single = false)
{
EnsureCosmosSqlClient();
return(CosmosSqlClient.UpsertDocumentInternal(CosmosSerializer.ToGraphEdge(edge, source, target, single)));
}
/// <summary>
/// Insert an edge into the database by providing the Edge domain model and references to its source and target as domain models
/// This call uses the SQL API to insert the edge as a document.
/// </summary>
/// <param name="edge">Edge entity to insert</param>
/// <param name="source">Source vertex of the edge</param>
/// <param name="target">Target vertex of the edge</param>
/// <param name="single">
/// [Optional] Indicates if there can only be one edge of this kind between the 2 vertices. Defaults to false.
/// i.e an edge defining a 'isFriend' relationship between 2 people needs to be singe:true because only one friend edge makes sense.
/// i.e an edge defining a 'visited' relationship between a person and a restaurant needs to be single:false because a person can visit the restaurant multiple times
/// </param>
/// <exception cref="InvalidOperationException">Throws invalid operation exception if the GraphClient was initialized without a CosmosSQLClient</exception>
/// <remarks>Inserting the same edge twice with single:false will succeed and generate a new edge instance, while with single:true it will fail.</remarks>
/// <returns><see cref="CosmosResponse"/> that tracks success status along with various performance parameters</returns>
public Task <CosmosResponse> InsertEdge <T, U, V>(T edge, U source, V target, bool single = false)
{
EnsureCosmosSqlClient();
return(CosmosSqlClient.InsertDocumentInternal(CosmosSerializer.ToGraphEdge(edge, source, target, single)));
}
/// <summary>
/// Upsert (Insert or Update) multiple vertices into the database using a TPL Dataflow block.
/// This call uses the SQL API to upsert the vertex]ices as a document.
/// </summary>
/// <param name="entities">Entites to upsert</param>
/// <param name="reportingCallback">[Optional] Method to be called based on the <paramref name="reportingInterval"/>. Generally used to provide a progress update to callers. Defaults to null./></param>
/// <param name="reportingInterval">[Optional] interval in seconds to to call the reporting callback. Defaults to 10s</param>
/// <param name="threads">[Optional] Number of threads to use for the paralel execution. Defaults to 4</param>
/// <param name="cancellationToken">Cancellation token to cancel the operation</param>
/// <exception cref="InvalidOperationException">Throws invalid operation exception if the GraphClient was initialized without a <see cref="CosmosClientSql"/>.</exception>
/// <example>
/// <![CDATA[
/// await _client.UpsertVertex(elements, (partial) => { Console.WriteLine($"upserted {partial.Count()} vertices");
/// ]]>
/// </example>
/// <returns><see cref="CosmosResponse"/> that tracks success status along with various performance parameters.</returns>
public Task <IEnumerable <CosmosResponse> > UpsertVertex <T>(IEnumerable <T> entities, Action <IEnumerable <CosmosResponse> > reportingCallback = null, TimeSpan?reportingInterval = null, int threads = 4, CancellationToken cancellationToken = default(CancellationToken))
{
EnsureCosmosSqlClient();
//Could've used UpserVertex instead of the lambda, but I don't want to the EnsureCosmosClient() for every call
return(CosmosSqlClient.ProcessMultipleDocuments(entities, (T entity) => { return CosmosSqlClient.UpsertDocumentInternal(CosmosSerializer.ToGraphVertex <T>(entity)); }, reportingCallback, reportingInterval, threads, cancellationToken));
}
/// <summary>
/// Upsert (Insert or Update) a vertex into the database.
/// This call uses the SQL API to upsert the vertex as a document.
/// </summary>
/// <param name="entity">Entity to upsert</param>
/// <exception cref="InvalidOperationException">Throws invalid operation exception if the GraphClient was initialized without a CosmosSQLClient</exception>
/// <returns><see cref="CosmosResponse"/> that tracks success status along with various performance parameters</returns>
public Task <CosmosResponse> UpsertVertex <T>(T entity)
{
EnsureCosmosSqlClient();
return(CosmosSqlClient.UpsertDocumentInternal(CosmosSerializer.ToGraphVertex <T>(entity)));
}
