All Products
Search
Document Center

:bit_struct

Last Updated:Sep 09, 2021

You can use functionality functions in filter clauses to define filter conditions. Functionality functions that return numeric values can be used in sort clauses for sorting. The fields that you reference in parameters of functionality functions must be configured as index or attribute fields based on the description of each function.

Functionality functions

1.Introduction

bit_struct: This function splits each value into several parts for a field that is of the INT_ARRAY type and performs a specific operation on the several parts.

2.Syntax

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

3.Parameters

  • doc_field: a field of the INT_ARRAY type.

  • $struct_definition: the information about bit positions that is used to split each 64-bit integer in an array into multiple parts. Each part represents a dimension. You can specify the starting bit position and end bit position of each part. The starting bit position and end bit position are separated by a hyphen (-). For a 64-bit integer, the bits from the leftmost bit to the rightmost bit are numbered from 0 to 63. The end bit position of a part cannot exceed 63. Separate multiple parts with commas (,). The parts are numbered from 1. For example, you want to split a 64-bit integer into three parts. Each part represents a dimension. The bits from bit0 to bit9 indicate a value that is represented by $1. The bits from bit10 to bit48 indicate a value that is represented by $2. The bits from bit49 to bit60 indicate a value that is represented by $3. Then, you can set the $struct_definition parameter to "0-9,10-48,49-60".

  • operation: the operations to be performed on the parts. You can specify one to five operations. Operations are numbered after the parts that are specified by the $struct_definition parameter and the numbers of operations increase. When you specify multiple operations and an operation may reference the return value of a preceding operation, you can use the number of the preceding operation. The bit_struct function supports the following operations:

    • "equal,$m,$n": determines whether the value represented by $m equals the value represented by $n. If so, true is returned. If not, false is returned.

    • "overlap,$m,$n,$k,$p": determines whether the ranges defined by ($m,$n) and ($k,$p) intersect. If so, true is returned. If not, false is returned.

    • "and,$m,$n,… ": performs the AND logical operation on specified values, such as $m and &n. Note that the specified values of the operations can be integers. Example: "equal,$1,1".

4.Return value

The return value is a 64-bit integer that indicates the subscript of the array element for which the last operation returns true. The subscripts of array elements start from 0. If no array elements for which the last operation returns true exist, the bit_struct function returns -1.

5.Usage notes:

  • The field that you reference in the parameter of the function must be configured as an attribute field.

Sample scenarios

Search for the stores that are open in a specified period of time. If your document has the open_time field which is of the INT_ARRAY type. Each 64-bit integer in the array indicates the business hours of a store. The first 32 bits of an integer indicate the time when the store is open. The last 32 bits of an integer indicate the time when the store is closed. If you want to search for stores that are open from 14:00 to 15:30, you must first convert each of the start time and end time to the number of minutes that have elapsed from 00:00 on the same day. In this example, 14:00 is converted to 840 and 15:30 is converted to 930. Then, you can use the following filter clause:

filter=bit_struct(open_time, "0-31,32-63","overlap,$1,$2,840,930")!=-1
  • Search for the stores that can serve a number of customers to have breakfast, lunch, or dinner. The number of customers is specified by using a range with the minimum value and maximum value.

If your document has the book_info field which is of the INT_ARRAY type. Each 64-bit integer in the array indicates the book information of a store. The bits from bit0 to bit7 indicate the date. The bits from bit8 to bit15 indicate breakfast, lunch, or dinner. The bits from bit16 to bit41 indicate the minimum number of allowed customers. The bits from bit42 to bit63 indicate the maximum number of allowed customers. You can use the following filter clause to search for the stores that can serve three to five customers to have dinner tomorrow:

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
// Description:
$1 indicates the value that is represented by the bits from bit0 to bit7. 
$2 indicates the value that is represented by the bits from bit8 to bit15.
$3 indicates the value that is represented by the bits from bit16 to bit41.
$4 indicates the value that is represented by the bits from bit42 to bit63.
$5 indicates the return value of the "equal,$1,1" operation.
$6 indicates the return value of the "equal,$2,3" operation.
$7 indicates the return value of the "overlap,$3,$4,3,5" operation.
The "and,$5,$6,$7" operation performs the AND logical operation on the values represented by $5, $6, and $7. The return value of the bit_struct function indicates the subscript of the array element for which the "and,$5,$6,$7" returns true.
  • Search for the stores that can provide more than 10 commodities and deliver commodities from 14:00 to 15:30. 14:00 is converted to 840 and 15:30 is converted to 930. To search for such stores, you need to set filter conditions based on two fields. The bit_struct function returns an array subscript only for one field. Therefore, you can use the bit_struct function in the multi_attr function to reference two fields of an array type. The multi_attr function can return an array subscript for the other field. In this example, you can use the following query clause:

filter=multi_attr(store, bit_struct(dispatch_time,"0-31,32-63", "equal,$1,840", "equal,$2,930", "and,$3,$4"))>10
// Description:
The dispatch_time field is of the INT_ARRAY type and has multiple values. Each value is a 64-bit integer that indicates the delivery time of a store. You must first convert the time to the number of minutes that have elapsed from 00:00 on the same day. In this example, 14:00 is converted to 840 and 15:30 is converted to 930.
The store field is of the INT_ARRAY type and has multiple values. Each value is a 64-bit integer that indicates the inventory of a store. Each value of the store field corresponds to each value of the dispatch_time field.

Construct a value for a field of the INT_ARRAY type

Example:

In this example, you can generate a 64-bit integer by using the dome calculator in Python. The integer indicates the time period from 08:00 to 18:00.

# Convert the start time to the number of minutes between 00:00 and 08:00.
start=8*60

# Convert the end time to the number of minutes between 00:00 and 18:00.
end=18*60

# Use the first 32 bits of the 64-bit integer to indicate the start time and the last 32 bits to indicate the end time.
# Generate the initial 64-bit integer whose first 32 bits indicates 08:00.
start=start<<32
Print ("First 32 bits",start)#2061584302080

# Generate the final 64-bit integer that uses the first 32 bits to indicate 08:00 and the last 32 bits to indicate 18:00.
result=start|end
print("result",result)#2061584303160

Result

1

Principle: The following figures show how 480 and 1080 are converted to binary numbers.

2

Use the first 32 bits to indicate 480 by performing a left bit shift.

3

Replace the last 32 bits in the binary number that is generated after the left bit shift with that in the binary number of 1080.

4

Convert the final binary number into a decimal number. The final binary number is 0000000000000000000000011110000000000000000000000000010000111000.

5

The decimal number is the same as the result generated by using the dome calculator in Python.

Example:

If you want to check whether the last 32 bits of a value in an array represents a specific number, you can use the following sample filter clause:

bit_struct(type_arr,"0-31,32-63","equal,$2,40506")!=-1
// Description:
"0-31,32-63": the information about bit positions that is used to split a value into two parts.
"equal,$2,40506": the operation that checks whether the last 32 bits of a value indicates 40506.