private InternalFilter(FieldPath field, int op, Value value)
{
Field = field;
_op = op;
_value = value;
}
private Query OrderBy(string fieldPath, Direction direction)
{
GaxPreconditions.CheckNotNullOrEmpty(fieldPath, nameof(fieldPath));
return(OrderBy(FieldPath.FromDotSeparatedString(fieldPath), direction));
}
internal InternalOrdering(FieldPath field, Direction direction)
{
Field = field;
Direction = direction;
}
// Note: the two general Where methods were originally public, accepting a public QueryOperator enum.
// If we ever want to make them public again, we should reinstate the QueryOperator enum to avoid an API
// dependency on the proto enum.
/// <summary>
/// Add a filter for the given field path.
/// </summary>
/// <remarks>
/// This call adds additional filters to any previously-specified ones.
/// </remarks>
/// <param name="fieldPath">The dot-separated field path to filter on. Must not be null or empty.</param>
/// <param name="op">The filter operator. Must not be null.</param>
/// <param name="value">The value to compare in the filter.</param>
/// <returns>A new query based on the current one, but with the additional specified filter applied.</returns>
private Query Where(string fieldPath, FieldOp op, object value)
{
GaxPreconditions.CheckNotNullOrEmpty(fieldPath, nameof(fieldPath));
return(Where(FieldPath.FromDotSeparatedString(fieldPath), op, value));
}
/// <summary>
/// Adds an additional descending ordering by the specified path.
/// </summary>
/// <remarks>
/// <para>
/// Unlike LINQ's OrderBy method, this call adds additional subordinate orderings to any
/// additionally specified. So <c>query.OrderBy("foo").OrderByDescending("bar")</c> is similar
/// to a LINQ <c>query.OrderBy(x => x.Foo).ThenByDescending(x => x.Bar)</c>.
/// </para>
/// <para>
/// This method cannot be called after a start/end cursor has been specified with
/// <see cref="StartAt(object[])"/>, <see cref="StartAfter(object[])"/>, <see cref="EndAt(object[])"/> or <see cref="EndBefore(object[])"/>.
/// </para>
/// </remarks>
/// <param name="fieldPath">The field path to order by. Must not be null.</param>
/// <returns>A new query based on the current one, but with the additional specified ordering applied.</returns>
public Query OrderByDescending(FieldPath fieldPath) => OrderBy(GaxPreconditions.CheckNotNull(fieldPath, nameof(fieldPath)), Direction.Descending);
/// <summary>
/// Adds an operation to update a document's data in this transaction.
/// </summary>
/// <param name="documentReference">A document reference indicating the path of the document to update. Must not be null.</param>
/// <param name="updates">The updates to perform on the document, keyed by the dot-separated field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.</param>
/// <param name="precondition">Optional precondition for updating the document. May be null, which is equivalent to <see cref="Precondition.MustExist"/>.</param>
public void Update(DocumentReference documentReference, IDictionary <string, object> updates, Precondition precondition = null)
{
GaxPreconditions.CheckNotNull(updates, nameof(updates));
Update(documentReference, updates.ToDictionary(pair => FieldPath.FromDotSeparatedString(pair.Key), pair => pair.Value), precondition);
}
/// <summary> /// Returns a query with a filter specifying that the value in <paramref name="fieldPath"/> must be greater than or /// equal to <paramref name="value"/>. /// </summary> /// <remarks> /// This call adds additional filters to any previously-specified ones. /// </remarks> /// <param name="fieldPath">The field path to filter on. Must not be null.</param> /// <param name="value">The value to compare in the filter.</param> /// <returns>A new query based on the current one, but with the additional specified filter applied.</returns> public Query WhereGreaterThanOrEqualTo(FieldPath fieldPath, object value) => Where(fieldPath, FieldOp.GreaterThanOrEqual, value);
/// <summary> /// Returns a query with a filter specifying that the value in <paramref name="fieldPath"/> must be less than /// <paramref name="value"/>. /// </summary> /// <remarks> /// This call adds additional filters to any previously-specified ones. /// </remarks> /// <param name="fieldPath">The field path to filter on. Must not be null.</param> /// <param name="value">The value to compare in the filter.</param> /// <returns>A new query based on the current one, but with the additional specified filter applied.</returns> public Query WhereLessThan(FieldPath fieldPath, object value) => Where(fieldPath, FieldOp.LessThan, value);
/// <summary> /// Returns a query with a filter specifying that the value in <paramref name="fieldPath"/> must be less than or /// equal to <paramref name="value"/>. /// </summary> /// <remarks> /// This call adds additional filters to any previously-specified ones. /// </remarks> /// <param name="fieldPath">The field path to filter on. Must not be null.</param> /// <param name="value">The value to compare in the filter.</param> /// <returns>A new query based on the current one, but with the additional specified filter applied.</returns> public Query WhereLessThanOrEqualTo(FieldPath fieldPath, object value) => Where(fieldPath, FieldOp.LessThanOrEqual, value);
/// <summary> /// Determines whether or not the given field path is present in the document. If this snapshot represents /// a missing document, this method will always return false. /// </summary> /// <param name="path">The field path to check. Must not be null.</param> /// <returns>true if the specified path represents a field in the document; false otherwise</returns> public bool ContainsField(FieldPath path) => ExtractValue(path) != null;
/// <summary> /// Returns a query with a filter specifying that the value in <paramref name="fieldPath"/> must be /// equal to <paramref name="value"/>. /// </summary> /// <remarks> /// This call adds additional filters to any previously-specified ones. /// </remarks> /// <param name="fieldPath">The field path to filter on. Must not be null.</param> /// <param name="value">The value to compare in the filter.</param> /// <returns>A new query based on the current one, but with the additional specified filter applied.</returns> public Query WhereEqualTo(FieldPath fieldPath, object value) => Where(fieldPath, FieldOp.Equal, value);
/// <summary> /// Determines whether or not the given field path is present in the document. If this snapshot represents /// a missing document, this method will always return false. /// </summary> /// <param name="path">The dot-separated field path to check. Must not be null or empty.</param> /// <returns>true if the specified path represents a field in the document; false otherwise</returns> public bool ContainsField(string path) => ContainsField(FieldPath.FromDotSeparatedString(path));
/// <summary> /// Attempts to fetch the given field path from the document, returning whether or not it was found, and deserializing /// it if it was found. /// </summary> /// <remarks> /// This method does not throw an exception if the field is not found, but does throw an exception if the field was found /// but cannot be deserialized. /// </remarks> /// <typeparam name="T">The type to deserialize the value to, if it is found.</typeparam> /// <param name="path">The dot-separated field path to fetch. Must not be null or empty</param> /// <param name="value">When this method returns, contains the deserialized value if the field was found, or the default value /// of <typeparamref name="T"/> otherwise.</param> /// <returns>true if the field was found; false otherwise.</returns> public bool TryGetValue <T>(string path, out T value) => TryGetValue(FieldPath.FromDotSeparatedString(path), out value);
/// <summary> /// Fetches a field value from the document, throwing an exception if the field does not exist. /// </summary> /// <param name="path">The dot-separated field path to fetch. Must not be null or empty</param> /// <exception cref="InvalidOperationException">The field does not exist in the document data.</exception> /// <returns>The deserialized value.</returns> public T GetValue <T>(string path) => GetValue <T>(FieldPath.FromDotSeparatedString(path));
/// <summary>
/// Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.
/// </summary>
/// <param name="updates">The updates to perform on the document, keyed by the dot-separated field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.</param>
/// <param name="precondition">Optional precondition for updating the document. May be null, which is equivalent to <see cref="Precondition.MustExist"/>.</param>
/// <param name="cancellationToken">A cancellation token to monitor for the asynchronous operation.</param>
/// <returns>The write result of the server operation.</returns>
public Task <WriteResult> UpdateAsync(IDictionary <string, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default)
{
GaxPreconditions.CheckNotNull(updates, nameof(updates));
return(UpdateAsync(updates.ToDictionary(pair => FieldPath.FromDotSeparatedString(pair.Key), pair => pair.Value), precondition, cancellationToken));
}
/// <summary> /// Returns a query with a filter specifying that the value in <paramref name="fieldPath"/> must be greater than /// <paramref name="value"/>. /// </summary> /// <remarks> /// This call adds additional filters to any previously-specified ones. /// </remarks> /// <param name="fieldPath">The field path to filter on. Must not be null.</param> /// <param name="value">The value to compare in the filter.</param> /// <returns>A new query based on the current one, but with the additional specified filter applied.</returns> public Query WhereGreaterThan(FieldPath fieldPath, object value) => Where(fieldPath, FieldOp.GreaterThan, value);
internal SentinelField(FieldPath fieldPath, Value value)
{
FieldPath = fieldPath;
Value = value;
}
/// <summary>
/// Returns an instance that merges the given fields.
/// </summary>
/// <param name="fieldMask">The fields to merge. An empty array is equivalent to using <see cref="MergeAll"/>.
/// Must not be null or contain any empty or null elements. Each field is treated as a dot-separated list of segments.
/// </param>
/// <returns>An instance that merges the given fields.</returns>
public static SetOptions MergeFields(params string[] fieldMask)
{
GaxPreconditions.CheckNotNull(fieldMask, nameof(fieldMask));
GaxPreconditions.CheckArgument(fieldMask.All(x => !string.IsNullOrEmpty(x)), nameof(fieldMask), "Field mask must not contain any null or empty elements");
return(new SetOptions(true, fieldMask.Select(field => FieldPath.FromDotSeparatedString(field)).ToArray()));
}