About the parentId Property

This is for:

Developer System Administrator

When adding or updating items in a Push source, you can use the parentId property to define parent-child relationships between those items. Doing so populates a set of fields that you can leverage in nested queries.

Using the parentId property doesn’t populate any field that would allow you to load the parent of a folded collection.

If you want to request and render folded results from a Push source, you should therefore rather define your parent-child relationships by sending metadata to populate the standard folding fields in your index (that is, @foldingcollection, @foldingparent, and @foldingchild).

Defining Parent-Child Relationships

You can use the parentId property to define simple parent-child relationships between items in a Push source.

To do so:

  • If an item is the parent of a relationship, set its parentId to its own documentId.

  • If an item is a child in a relationship, set its parentId to the documentId of its parent.

Specifying a parentId when pushing an item always populates the @topparentid field for that item.

If the parentId value differs from the documentId value of the pushed item, the @attachmentparentid field gets populated as well.

In a Push source, you want to define simple parent-child relationships between items representing directors and movies.

  1. You create a file container.

    POST https://api.cloud.coveo.com/push/v1/organizations/coveomovieorganization/files HTTP/1.1
 
Authorization: Bearer **********-****-****-****-************

  2. You upload a batch of items into the file container you previously created, using the parentId property to define the desired relationships.

    Request

    PUT https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/coveomovieorganization/2a65f989-2371-4dc6-b6aa-198b5b88ff29?x-amz-security-token=FQoGZXIvYXdzEB8aDL37SykFY6%2FzbYBDPCLlAQmJ0nWbMK0Bxq3wcGnEq1bPcDGsP7dTaKkuuAPOA7LaNZhosW3d8ybg14N8o9OAaUS%2BoQ9Y1oZROmh%2BHZbP7krJAlDRUQS2NtrGxUh20h3GInWxTM5CZ86p5een1Gzsk%2FuCrKCXpqGFJZ1UwEFkEGtj2M2l%2F3eOhfPd6ga9%2F51NgHQPXRc4z%2F5NLiEfWlv%2FxzLZHrtznCjj8fi77QKcLkzO9kiLOtWtZVxmoMg4jVZYwZuOdfRqAVEzaWIsP8lQ2O5AWTwD5O8HKjmtO6v%2FZiV9diYDx7Z7WtrKJg1v2upFHhxljxUo6%2BCG2wU%3D&AWSAccessKeyId=ASIAYKDJLZIT5VRAMAJE&Expires=1533134515&Signature=fyZW7rDLYWSt%2B6rRTPaQPc72uUY%3D HTTP/1.1
 
Content-Type: application/octet-stream
x-amz-server-side-encryption: "AES256"

    Payload

    {
  "addOrUpdate": [
    {
      "title": "Edgar Wright",
      "data": "...",
      "documentId": "file://directors/edgar-wright.txt",
      "parentId": "file://directors/edgar-wright.txt",
      "documenttype": "Director"
    },
    {
      "title": "The World's End",
      "data": "...",
      "documentId": "file://movies/the-world-s-end.txt",
      "parentId": "file://directors/edgar-wright.txt",
      "documenttype": "Movie"
    },
    {
      "title": "Baby Driver",
      "data": "...",
      "documentId": "file://movies/baby-driver.txt",
      "parentId": "file://directors/edgar-wright.txt",
      "documenttype": "Movie"
    },
    {
      "title": "Stanley Kubrick",
      "data": "...",
      "documentId": "file://directors/stanley-kubrick.txt",
      "parentId": "file://directors/stanley-kubrick.txt",
      "documenttype": "Director"
    },
    {
      "title": "The Shining",
      "data": "...",
      "documentId": "file://movies/the-shining.txt",
      "parentId": "file://directors/stanley-kubrick.txt",
      "documenttype": "Movie"
    }
  ],
  "delete": []
}

  3. You push the file container to your source.

    POST https://api.cloud.coveo.com/push/v1/organizations/coveomovieorganization/sources/vzievcixq66qq5q6xulpy32dqi-coveomovieorganization/documents/batch?fileId=b5e8767e-8f0d-4a89-9095-1127915c89c7 HTTP/1.1
 
Authorization: Bearer **********-****-****-****-************

When the indexing pipeline finishes processing the batch, the @topparentid and @attachmentparentid fields are populated as follows:

Item title Document type @topparentid value @attachmentparentid value
Edgar Wright Director 32345 N/A
Stanley Kubrick Director 32338 N/A
The World’s End Movie 32345 32345
Baby Driver Movie 32345 32345
The Shining Movie 32338 32338

Leveraging ParentId-Generated Fields in Nested Queries

The @topparentid and @attachmentparentid numeric fields can be useful in nested queries.

Ensure that the Use Cache For Numeric Queries field parameter is enabled for nested query fields (see Add or edit a field). Doing so will allow for quicker numeric operations (for example, comparing integers), making query executions faster.

When querying items from the Push source described in the Defining Parent-Child Relationships example, you could use the following nested query to retrieve all movies by director Edgar Wright:

[[@attachmentparentid] @topparentid==32345]

Query response excerpt

{
  "totalCount": 2,
  ...
  "results": [
    {
      "title": "Baby Driver",
      "uri": "file://movies/baby-driver.txt",
      ...
      "raw": {
        ...
        "attachmentparentid": 32345,
        "topparentid": 32345,
        ...
      }
      ...
    },
    {
      "title": "The World's End",
      "uri": "file://movies/the-world-s-end.txt",
      ...
      "raw": {
        ...
        "attachmentparentid": 32345,
        "topparentid": 32345,
        ...
      }
      ...
    }
  ]
}