CBLQueryFunction

@interface CBLQueryFunction : NSObject

CBLQueryFunction provides query functions.

  • Creates an AVG(expr) function expression that returns the average of all the number values in the group of the values expressed by the given expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)avg:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The expression.

    Return Value

    The AVG(expr) function.

  • Creates a COUNT(expr) function expression that returns the count of all values in the group of the values expressed by the given expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)count:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The expression.

    Return Value

    The COUNT(expr) function.

  • Creates a MIN(expr) function expression that returns the minimum value in the group of the values expressed by the given expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)min:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The expression.

    Return Value

    The MIN(expr) function.

  • Creates a MAX(expr) function expression that returns the maximum value in the group of the values expressed by the given expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)max:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The expression.

    Return Value

    The MAX(expr) function.

  • Creates a SUM(expr) function expression that return the sum of all number values in the group of the values expressed by the given expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)sum:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The expression.

    Return Value

    The SUM(expr) function.

  • Creates an ABS(expr) function that returns the absolute value of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)abs:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The ABS(expr) function.

  • Creates an ACOS(expr) function that returns the inverse cosine of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)acos:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The ACOS(expr) function.

  • Creates an ASIN(expr) function that returns the inverse sin of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)asin:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The ASIN(expr) function.

  • Creates an ATAN(expr) function that returns the inverse tangent of the numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)atan:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The ATAN(expr) function.

  • Creates an ATAN2(Y, X) function that returns the arctangent of y/x.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)atan2:(nonnull CBLQueryExpression *)y
                                        x:(nonnull CBLQueryExpression *)x;

    Parameters

    y

    The expression to evaluate as the Y coordinate.

    x

    The expression to evaluate as the X coordinate.

    Return Value

    The ATAN2(Y, X) function.

  • Creates a CEIL(expr) function that returns the ceiling value of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)ceil:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The CEIL(expr) function.

  • Creates a COS(expr) function that returns the cosine of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)cos:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The COS(expr) function.

  • Creates a DEGREES(expr) function that returns the degrees value of the given radiants value expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)degrees:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression to evaluate as a radiants value.

    Return Value

    The DEGREES(expr) function.

  • +e

    Creates a E() function that return the value of the mathemetical constant ‘e’.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)e;

    Return Value

    The E() constant function.

  • Creates a EXP(expr) function that returns the value of ‘e’ power by the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)exp:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The EXP(expr) function.

  • Creates a FLOOR(expr) function that returns the floor value of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)floor:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The FLOOR(expr) function.

  • Creates a LN(expr) function that returns the natural log of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)ln:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The LN(expr) function.

  • Creates a LOG(expr) function that returns the base 10 log of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)log:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The LOG(expr) function.

  • +pi

    Creates a PI() function that returns the mathemetical constant Pi.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)pi;

    Return Value

    The PI() constant function.

  • Creates a POWER(base, exponent) function that returns the value of the given base expression power the given exponent expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)power:(nonnull CBLQueryExpression *)base
                                 exponent:(nonnull CBLQueryExpression *)exponent;

    Parameters

    base

    The base expression.

    exponent

    The exponent expression.

    Return Value

    The POWER(base, exponent) function.

  • Creates a RADIANS(expr) function that returns the radians value of the given degrees value expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)radians:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression to evaluate as a degrees value.

    Return Value

    The RADIANS(expr) function.

  • Creates a ROUND(expr) function that returns the rounded value of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)round:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The ROUND(expr) function.

  • Creates a ROUND(expr, digits) function that returns the rounded value to the given number of digits of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)round:(nonnull CBLQueryExpression *)expression
                                   digits:(nonnull CBLQueryExpression *)digits;

    Parameters

    expression

    The numeric expression.

    digits

    The number of digits.

    Return Value

    The ROUND(expr, digits) function.

  • Creates a SIGN(expr) function that returns the sign (1: positive, -1: negative, 0: zero) of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)sign:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The SIGN(expr) function.

  • Creates a SIN(expr) function that returns the sin of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)sin:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The SIN(expr) function.

  • Creates a SQRT(expr) function that returns the square root of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)sqrt:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The SQRT(expr) function.

  • Creates a TAN(expr) function that returns the tangent of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)tan:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The TAN(expr) function.

  • Creates a TRUNC(expr) function that truncates all of the digits after the decimal place of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)trunc:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric expression.

    Return Value

    The trunc function.

  • Creates a TRUNC(expr, digits) function that truncates the number of the digits after the decimal place of the given numeric expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)trunc:(nonnull CBLQueryExpression *)expression
                                   digits:(nonnull CBLQueryExpression *)digits;

    Parameters

    expression

    The numeric expression.

    digits

    The number of digits.

    Return Value

    The TRUNC(expr, digits) function.

  • Creates a CONTAINS(expr, substr) function that evaluates whether the given string expression conatins the given substring expression or not.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)
         contains:(nonnull CBLQueryExpression *)expression
        substring:(nonnull CBLQueryExpression *)substring;

    Parameters

    expression

    The string expression.

    substring

    The substring expression.

    Return Value

    The CONTAINS(expr, substr) function.

  • Creates a LENGTH(expr) function that returns the length of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)length:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The LENGTH(expr) function.

  • Creates a LOWER(expr) function that returns the lowercase string of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)lower:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The LOWER(expr) function.

  • Creates a LTRIM(expr) function that removes the whitespace from the beginning of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)ltrim:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The LTRIM(expr) function.

  • Creates a RTRIM(expr) function that removes the whitespace from the end of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)rtrim:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The RTRIM(expr) function.

  • Creates a TRIM(expr) function that removes the whitespace from the beginning and ‘ the end of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)trim:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The TRIM(expr) function.

  • Creates a UPPER(expr) function that returns the uppercase string of the given string expression.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)upper:(nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The string expression.

    Return Value

    The UPPER(expr) function.

  • Creates a STR_TO_MILLIS(expr) function that returns the number of milliseconds since the unix epoch of the given ISO 8601 date time string expression.

    Note

    Valid date strings must start with a date in the form YYYY-MM-DD (time only strings are not supported).

    Times can be of the form HH:MM, HH:MM:SS, or HH:MM:SS.FFF. Leading zero is not optional (i.e. 02 is ok, 2 is not). Hours are in 24-hour format. FFF represents milliseconds, and trailing zeros are optional (i.e. 5 == 500).

    Time zones can be in one of three forms: (+/-)HH:MM (+/-)HHMM Z (which represents UTC)

    No time zone present will default to the device local time zone.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)stringToMillis:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The validly formatted ISO 8601 date time string expression.

    Return Value

    The corresponding function that converts the date time string to timestamp.

  • Creates a STR_TO_UTC(expr) function that returns the ISO 8601 UTC datetime string of the given ISO 8601 date time string expression.

    Note

    Valid date strings must start with a date in the form YYYY-MM-DD (time only strings are not supported).

    Times can be of the form HH:MM, HH:MM:SS, or HH:MM:SS.FFF. Leading zero is not optional (i.e. 02 is ok, 2 is not). Hours are in 24-hour format. FFF represents milliseconds, and trailing zeros are optional (i.e. 5 == 500).

    Time zones can be in one of three forms: (+/-)HH:MM (+/-)HHMM Z (which represents UTC)

    No time zone present will default to the device local time zone.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)stringToUTC:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The validly formatted ISO 8601 date time string expression.

    Return Value

    The corresponding function that converts the string to UTC string.

  • Creates a MILLIS_TO_STR(expr) function that returns a ISO 8601 date time string in device local timezone of the given number of milliseconds since the unix epoch expression.

    Note

    If the input expression is not numeric, then the result will be null.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)millisToString:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric value representing milliseconds since the unix epoch.

    Return Value

    The corresponding function that converts the timestamp to the ISO 8601 date string.

  • Creates a MILLIS_TO_UTC(expr) function that returns the UTC ISO 8601 date time string of the given number of milliseconds since the unix epoch expression.

    Note

    If the input expression is not numeric, then the result will be null.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)millisToUTC:
        (nonnull CBLQueryExpression *)expression;

    Parameters

    expression

    The numeric value representing milliseconds since the unix epoch.

    Return Value

    The corresponding function that converts the timestamp into the UTC ISO 8601 string.

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;
  • ENTERPRISE EDITION ONLY

    Creates prediction function with the given model name and input. When running a query with the prediction function, the corresponding predictive model registered to CBLDatabase class will be called with the given input to predict the result.

    The prediction result returned by the predictive model will be in a form dictionary object. To create an expression that refers to a property in the prediction result, the -property: method of the created CBLQueryPredictionFunction object can be used.

    Declaration

    Objective-C

    + (nonnull CBLQueryPredictionFunction *)
        predictionUsingModel:(nonnull NSString *)model
                       input:(nonnull CBLQueryExpression *)input;

    Parameters

    model

    The predictive model name registered to the CouchbaseLite Database.

    input

    The expression evaluated to a dictionary.

    Return Value

    A CBLQueryPredictionFunction object.

  • ENTERPRISE EDITION ONLY

    Creates a function that returns the euclidean distance between the two input vectors. The result is a non-negative floating-point number. The expression1 and expression2 must be arrays of numbers, and must be the same length.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)
        euclideanDistanceBetween:(nonnull CBLQueryExpression *)expression1
                             and:(nonnull CBLQueryExpression *)expression2;

    Parameters

    expression1

    The expression evaluated to an arrays of numbers.

    expression2

    The expression evaluated to an arrays of numbers.

    Return Value

    The euclient distance between two given input vectors.

  • ENTERPRISE EDITION ONLY

    Creates a function that returns the squared euclidean distance between the two input vectors. The result is a non-negative floating-point number. The expression1 and expression2 must be arrays of numbers, and must be the same length.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)
        squaredEuclideanDistanceBetween:(nonnull CBLQueryExpression *)expression1
                                    and:(nonnull CBLQueryExpression *)expression2;

    Parameters

    expression1

    The expression evaluated to an arrays of numbers.

    expression2

    The expression evaluated to an arrays of numbers.

    Return Value

    The squared euclient distance between two given input vectors.

  • ENTERPRISE EDITION ONLY

    Creates a function that returns the cosine distance which one minus the cosine similarity between the two input vectors. The result is a floating-point number ranges from −1.0 to 1.0. The expression1 and expression2 must be arrays of numbers, and must be the same length.

    Declaration

    Objective-C

    + (nonnull CBLQueryExpression *)
        cosineDistanceBetween:(nonnull CBLQueryExpression *)expression1
                          and:(nonnull CBLQueryExpression *)expression2;

    Parameters

    expression1

    The expression evaluated to an arrays of numbers.

    expression2

    The expression evaluated to an arrays of numbers.

    Return Value

    The cosine distance between two given input vectors.