Nested query

Limitations

• An OBJECT type field cannot be set as a primary key.

• An OBJECT type field does not support multi-value attributes.

• An OBJECT type field cannot be used as a vector field.

• You cannot configure a data source or data processing for an OBJECT type field.

• You cannot nest vector fields inside an OBJECT type field.

Configure an OBJECT field

When adding or modifying a table, you can add an OBJECT type field and configure its schema in the Field Configuration step.

Add an OBJECT field

1. On the field configuration page, click + Import Fields or manually add a new field row.

2. In the Field Type column, select OBJECT from the drop-down list.

3. After you select the OBJECT type, the Primary Key and Multi-value options become unavailable, and the Vector Field and Data Source options are disabled.

Configure schema

1. In the field list, find the row for the OBJECT field and click Configure schema. The schema configuration drawer appears on the right.

2. In the input box, enter a valid, non-empty JSON object for the schema configuration.

3. Click OK to complete the schema configuration.

A schema defines the internal structure of an OBJECT field, including the field type and index type of its sub-fields. The following is an example of a schema with a nested structure:

{
    "fields": {
        "age": {
            "field_type": "INTEGER",
            "index_type": "NUMBER"
        },
        "name": {
            "field_type": "STRING",
            "index_type": "STRING"
        },
        "tags": {
            "fields": {
                "k1": {
                    "field_type": "STRING",
                    "index_type": "STRING"
                },
                "k2": {
                    "field_type": "STRING",
                    "index_type": "STRING"
                }
            },
            "is_nested": true
        }
    },
    "is_nested": true
}

The following table describes the parameters in the schema.

Source data

• Full data

  JSON format

  {
  	"className": "c1",
  	"students": [{
  		"age": 6,
  		"name": "s1",
  		"tags": [{
  			"k1": "v1",
  			"k2": "v2"
  		}, {
  			"k1": "v11",
  			"k2": "v22"
  		}]
  	}]
  }

  ha3 format

  CMD=add^_
  className=c1^_
  students=[{"age":6,"name":"s1","tags":[{"k1":"v1","k2":"v2"},{"k1":"v11","k2":"v22"}]}]^_
  ^^  

• Real-time

  [
      {
          "cmd": "add",
          "fields": {
              "className": "c1",
              "students": "[{\"age\":6,\"name\":\"s1\",\"tags\":[{\"k1\":\"v1\",\"k2\":\"v2\"},{\"k1\":\"v11\",\"k2\":\"v22\"}]}]"
          }
      }
  ] 

Push data

When you push real-time data via an API, the value for the OBJECT field must be a JSON-formatted string.

Example of pushing data

Suppose a class table contains a regular field className and an OBJECT field students. The students field contains the age, name, and tags sub-fields. The following is an example of how to push a piece of data:

[
    {
        "cmd": "add",
        "fields": {
            "className": "c1",
            "students": "[{\"age\":6,\"name\":\"s1\",\"tags\":[{\"k1\":\"v1\",\"k2\":\"v2\"},{\"k1\":\"v11\",\"k2\":\"v22\"}]}]"
        }
    }
]

Nested query

Construct sub-field paths by joining the OBJECT field name and its sub-field names with underscores (_).

Query syntax

The format for referencing a sub-field of an OBJECT is: OBJECT_field_name_sub-field_name. For multi-level nesting, concatenate the names sequentially by using underscores: OBJECT_field_name_sub-field1_sub-field2.

For example, for the OBJECT field students, the query path for its sub-field age is students_age, and the query path for the nested sub-field tags.k1 is students_tags_k1.

Nested query behavior

When is_nested in the schema is set to true, the query conditions must be met within the same nested object. This means:

• If an OBJECT field contains an array of objects, each condition in the query must be met by a single element in that array.

• The query does not match field values across different objects in the array.

Query examples

Assume that the following data has been pushed, where the tags sub-field of the OBJECT field students is configured with is_nested: true:

{
    "className": "c1",
    "students": [
        {
            "age": 6,
            "name": "s1",
            "tags": [
                {"k1": "v1", "k2": "v2"},
                {"k1": "v11", "k2": "v22"}
            ]
        }
    ]
}

Example 1: Cross-object query (no result)

Query conditions: className is c1, students -> tags -> k1 is v1, and students -> tags -> k2 is v22.

query=className:c1 AND students_tags_k1:v1 AND students_tags_k2:v22

Result: No result. The query returns no result because k1:v1 and k2:v22 exist in different objects within the tags array. Since independent storage requires all conditions to match within a single nested object, no document is returned.

Example 2: Same-object query (returns a result)

Query conditions: className is c1, students -> tags -> k1 is v1, and students -> tags -> k2 is v2.

query=className:c1 AND students_tags_k1:v1 AND students_tags_k2:v2

Result: Returns a matching document. The conditions k1:v1 and k2:v2 are both met by the first object in the tags array. Therefore, the query succeeds and returns a matching document.

{
    "className": "c1",
    "students": "[{\"age\":6,\"name\":\"s1\",\"tags\":[{\"k1\":\"v1\",\"k2\":\"v2\"},{\"k1\":\"v11\",\"k2\":\"v22\"}]}]"
}

Flattened storage mode

When is_nested in the schema is set to false (the default value), the sub-fields of an OBJECT field use flattened storage. In this case, queries do not require conditions to match within the same nested object, and field values from different objects may be cross-matched.

You can determine the current storage mode by checking the schema configuration of the OBJECT field to see if it contains "is_nested": true. If the schema does not contain this parameter or its value is false, this indicates that flattened storage is used.