# UserMetaFields

An operation to perform on document fields to create a new metafield, which you can use in your query for further processing. To create a user metafield, set this parameter to an operation in the following format:

    UserMetaFields=OPERATION{UserFieldName}:DocumentFieldName

where,

`OPERATION` | is the operation that you want to perform on the contents of the specified fields in your documents.
`UserFieldName` | is the name of the user metafield that you want to create.
`DocumentFieldName` | is the name of the fields in your documents that you want to run the specified operation on. To specify multiple fields, separate the field names with colons (`:`) (there must be no space before or after a colon).

You can optionally use a constant in the `UserMetaFields` definition, in the following form:

    UserMetaFields=OPERATION{UserFieldName,Constant}:DocumentFieldName

The constants can be positive or negative, and they can include decimals (for example, `1.23`) and scientific notation (for example, `1E2`). The meaning of the constants depends on the operation that you use.

NOTE: IDOL Server uses the constant only if the `DocumentFieldName` contains values. For example, for the operation `MIN{MINSCORE,10}:SCORE`, IDOL Server does not create a `MINSCORE` user metafield if the `SCORE` field is missing for a document.

You can perform the following operations on document fields.

Operation | Description | Constant
--- | --- | ---
`ADD` | The sum of all the values in the specified fields. | The initial value to add the field values to.
`SUB` | The value of the first field name (or the sum of the values in all instances of the first field name), minus the values of the remaining fields. | An additional value to subtract.
`MUL` | The product of all the values in the specified fields. | The initial value to multiple the field values by.
`DIV` | The value of the first field name (or the product of the non-zero values in all instances of the first field name), divided by the non-zero values from the remaining fields. | An additional value to divide by. If the constant value is 0, the constant is ignored.
`MIN` | The smallest value in the specified fields. | An initial value to include in the minimum calculation.
`MAX` | The highest value in the specified fields. | An initial value to include in the maximum calculation.
`MEAN` | The mean of the values in the specified fields. | No effect.
`COUNT` | The number of numeric values in the specified fields (it does not count any non-numeric values). | No effect.
`COUNTA` | The number of non-empty occurrences of the specified field, regardless of their value. | No effect.
`ABS` | The absolute value of the value in the specified field (that is, removing any negative sign). | No effect.
`ROUND` | The nearest integer to the value in the specified field, or the nearest multiple of the specified constant. | The accuracy to round to. For example, 0.01 rounds to two decimal places.
`FLOOR` | The nearest integer that is lower than the value in the specified field, or the nearest multiple of the specified constant lower than the value. | The accuracy to round down to. For example, 0.01 rounds to two decimal places.
`LOG` | The log (to the base of the specified constant) of the value of the first instance in a document of the specified field. The constant is required for this function. | The base of the log.
`POW` | The value of the first instance in a document of the specified field, raised to the power of the specified constant. The constant is required for this function. | The power to use.

NOTE: The `ABS`, `ROUND`, `FLOOR`, `LOG`, and `POW` operations act on a single value for each document. Micro Focus recommends that you use these operations on fields that have only a single value, or the output of other user metafield operations. If you apply these operations to a field with multiple values, it returns the result of the operation on the first field value, which might depend on your configuration.

You can also use the following distance operations. In this case, you must specify two constants and two field names that contain the location information.

Operation | Description | Constant
--- | --- | ---
`DISTSPHERICAL` | The distance in kilometers between the location specified by the constants, and the location specified by the document fields, in latitude and longitude. You can specify the location fields as two fields in the form `:LAT_FIELD:LONG_FIELD`, or a single field that contains Well-known text format POINT definitions. | The latitude and longitude of the location you want to calculate distances from. Specify these values as `lat,long`.
`DISTCARTESIAN` | The distance between the point specified by the constants, and the point specified by the document fields, in cartesian coordinates. You can specify the location fields as two fields in the form `:X_FIELD:Y_FIELD`, or a single field that contains Well-known text format POINT definitions. | The X and Y coordinate of the point that you want to calculate distances from. Specify these values as `X,Y`.

NOTE: The `DISTSPHERICAL` and `DISTCARTESIAN` operations act on a single pair of values for each document (one value for each coordinate). Micro Focus recommends that you use these operations on fields that have only a single value, or the output of other user metafield operations. If you apply these operations to a field with multiple values, it returns the result of the operation on the first field value, which might depend on your configuration.

If both of your coordinate fields are configured as NumericType, Micro Focus recommends that you set XMLFullStructure to `True` in your configuration. With this additional configuration, distance-based metafields always produce results consistent with distance-based sorting when there are multiple values.

To specify multiple operations, separate the operations with a plus (+) or a space.

IDOL Server does not permanently store the values for user metafields, but you can use the results in the Sort, FieldText, and PrintFields parameters of your query, or in the FieldName parameter for the GetQueryTagValues action. For example, you might create a metafield `TOTAL`, which is the sum of one or more `PRICE` fields in your document. You can then sort the query results by the value of the `TOTAL` field. If you use a metafield for GetQueryTagValues, the fields that you use to create the metafield do not have to be parametric. You can also use `UserMetaFields` as a parameter in the AgentParamsField for an AgentBoolean query.

You can apply `UserMetaFields` operations to other user metafields created in the same query. For example, you might use an operation to create one field, and then use that field in a second operation. You must create a metafield before you reference it in another operation (that is, the operation to create the field must appear to the left of the operation that uses it in the `UserMetaFields` parameter).

When you use your metafield in another operation, the field name has the format `autn_user_UserFieldName`, where `UserFieldName` is the value that you specified in the `UserMetaField` parameter.

NOTE: `UserMetaFields` operations are more efficient when you use them on fields that are configured as NumericType, except for the `COUNTA` operation, which is more efficient on fields that are configured as CountType or MatchType.

Actions: | Query GetQueryTagValues
Type: | String
Default: |
Example: | `UserMetaFields=ADD{TOTAL}:PRICE:TAX MIN{LOWSCORE}:REVIEWSCORE` In this example, IDOL Server adds the values of the `PRICE` and `TAX` fields, and creates a new `autn_user_TOTAL` field, which you can use in the Sort and FieldText parameters. It also takes the minimum value of the `REVIEWSCORE` fields in each document, and creates an `autn_user_LOWSCORE` field. `UserMetaFields=MUL{VAT,0.2}:PRICE ADD{TOTALPRICE}:autn_user_VAT:PRICE` In this example, IDOL Server multiplies the value of the `PRICE` field by 0.2 to create a new `autn_user_VAT` field. It then adds the value of the new `autn_user_VAT` field to the original `PRICE` field to calculate the value of the `autn_user_TOTALPRICE` field.
See Also: | Sort FieldText FieldName

_FT_HTML5_bannerTitle.htm