bit_struct

Features and functions

1. Introduction

bit_struct: Splits each value of an INT_ARRAY field into custom segments based on bit positions and performs specified operations on these segments.

2. Syntax

bit_struct(doc_field,"$struct_definition", operation,...)

3. Parameters

• doc_field: The name of a field of the INT_ARRAY type.

• $struct_definition: Splits an int64 value into multiple dimensions. Each dimension is defined by a start and end bit position, separated by a hyphen (-). Bit positions are zero-indexed and counted from the most significant bit. The valid range for bit positions is 0 to 63. You can define multiple dimensions by separating them with commas (,). Each dimension is assigned a number, starting from 1. For example, to split an int64 value into three dimensions where bits 0-9 represent the first value ($1), bits 10-48 represent the second value ($2), and bits 49-60 represent the third value ($3), set this parameter to "0-9,10-48,49-60".

• operation: Defines the operations to perform. You must define at least one and at most five operations. Each operation is assigned a number that increments from the last number used in $struct_definition. If you define multiple operations, a later operation can use the return value of a previous one by referencing its assigned number. The available operations are:

  • "equal,$m,$n": Checks if the value represented by $m is equal to the value represented by $n. Returns true if they are equal, and false otherwise.

  • "overlap,$m,$n,$k,$p": Checks if the range defined by ($m, $n) overlaps with the range defined by ($k, $p) on a number line. Returns true if they overlap, and false otherwise.

  • "and,$m,$n,...": Returns the result of a logical AND (&&) operation on $m, $n, and so on.

4. Return value

An int64 value. The function returns the zero-based index of the first element in doc_field for which the final operation evaluates to true. If no element in doc_field satisfies the specified operations, the function returns -1.

5. Notes

• Fields that depend on function parameters must be created as property fields.

Usage scenarios

Which shops are open during a specific time period? Assume that a document contains a field named open_time of the int64_array type, where each value represents a period of business hours. The high 32 bits of an int64 value represent the start time, and the low 32 bits represent the end time. To query for shops that are open from 14:00 to 15:30, you can convert this time range into minutes from the start of the day (00:00). For example, the time range from 14:00 to 15:30 is represented as (840, 930). The filter clause in the query can then be written as follows:

filter=bit_struct(open_time, "0-31,32-63","overlap,$1,$2,840,930")!=-1

• Query for stores that can serve a party of Pmin to Pmax people for a specific meal on a future day

Assume a document contains an int64_array field named book_info. In each value of this array, bits 0-7 represent the date, bits 8-15 represent the meal type, bits 16-41 represent the minimum party size, and bits 42-63 represent the maximum party size. To query for stores that can serve a party of 3 to 5 for dinner (meal type 3) tomorrow (date 1), you can write the filter clause as follows:

filter=bit_struct(book_info,"0-7,8-15,16-41,42-63",
"equal,$1,1","equal,$2,3","overlap,$3,$4,3,5","and,$5,$6,$7")!=-1
// Explanation
// $1 represents the value from bits 0-7 of book_info.
// $2 represents the value from bits 8-15 of book_info.
// $3 represents the value from bits 16-41 of book_info.
// $4 represents the value from bits 42-63 of book_info.
// $5 represents the return value of the operation "equal,$1,1".
// $6 represents the return value of the operation "equal,$2,3".
// $7 represents the return value of the operation "overlap,$3,$4,3,5".
// The function returns the array index in book_info that corresponds to the first time the logical AND of the values represented by $5, $6, and $7 is true.

• Query for stores with an Inventory > 10 between 14:00 and 15:30, which corresponds to the interval (840, 930). Because the bit_struct function returns an index, you can use it with the multi_attr function to retrieve the value from another array-type field at that index. For example, you can use the following in a query statement:

filter=multi_attr(store, bit_struct(dispatch_time,"0-31,32-63", "equal,$1,840", "equal,$2,930", "and,$3,$4"))>10
// Explanation
// dispatch_time is a multi-value INT64 field in the document that stores the merchant's delivery times. Convert the times into a period measured in minutes from the start of the day (00:00). The period from 14:00 to 15:30 is represented as (840, 930).
// store is an int64_array field where each value corresponds to a time period in dispatch_time and represents the inventory level for that period.

Constructing int64_array values

Example

This example uses Python to construct an int64 value for the time period from 8:00 to 18:00.

# Start time 8:00, in minutes
start=8*60

# End time 18:00
end=18*60

# Use the high 32 bits of the int64 for the start time and the low 32 bits for the end time.
# First, construct the high 32 bits.
start=start<<32
print("High 32 bits",start)#2061584302080

# Final result
result=start|end
print("Result",result)#2061584303160

Result: Diagram: The binary representation is . To store 480 in the high 32 bits, left-shift it by 32 bits: . Then, use the bitwise OR operator (|) to store 1080 in the low 32 bits: . The resulting binary value is 0000000000000000000000011110000000000000000000000000010000111000. The decimal result is , which matches the result from the Python example.

The following is a simple example.

Assume that you want to check whether an array contains a specific value, and this value is stored in the low 32 bits of an element. You can write the filter clause as follows:

bit_struct(type_arr,"0-31,32-63","equal,$2,40506")!=-1
// Explanation:
// "0-31,32-63": This is a fixed value.
// "equal,$2,40506": Checks if the array contains the value 40506.