// 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> /// 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> /// 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> /// 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));
}
private Query OrderBy(string fieldPath, Direction direction)
{
GaxPreconditions.CheckNotNullOrEmpty(fieldPath, nameof(fieldPath));
return(OrderBy(FieldPath.FromDotSeparatedString(fieldPath), direction));
}
/// <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 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()));
}
