---
title: "Indexing Hierarchical Data"
url: "https://docs.ravendb.net/6.2/indexes/indexing-hierarchical-data"
version: "6.2"
language: "php"
---

# Indexing Hierarchical Data

> Client language: PHP. Also available for [Java](https://docs.ravendb.net/6.2/indexes/indexing-hierarchical-data.java.md), [C#](https://docs.ravendb.net/6.2/indexes/indexing-hierarchical-data.md), [Python](https://docs.ravendb.net/6.2/indexes/indexing-hierarchical-data.python.md), [Node.js](https://docs.ravendb.net/6.2/indexes/indexing-hierarchical-data.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Use the `Recurse` method to traverse the layers of a hierarchical document and index its fields.
>
> - In this Page:
>   - [Hierarchical data](#hierarchical-data)
>   - [Index hierarchical data](#index-hierarchical-data)
>   - [Query the index](#query-the-index)

## Hierarchical data

One significant advantage of document databases is their tendency not to impose limits on data structuring.
**Hierarchical data structures** exemplify this quality well; for example, consider the commonly used comment thread, implemented using objects such as:

```php
class BlogPost
{
  private ?string $author = null;
  private ?string $title = null;
  private ?string $text = null;

  // Blog post readers can leave comments
  public ?BlogPostCommentList $comments = null;

  public function getAuthor(): ?string
  {
      return $this->author;
  }

  public function setAuthor(?string $author): void
  {
      $this->author = $author;
  }

  public function getTitle(): ?string
  {
      return $this->title;
  }

  public function setTitle(?string $title): void
  {
      $this->title = $title;
  }

  public function getText(): ?string
  {
      return $this->text;
  }

  public function setText(?string $text): void
  {
      $this->text = $text;
  }

  public function getComments(): ?BlogPostCommentList
  {
      return $this->comments;
  }

  public function setComments(?BlogPostCommentList $comments): void
  {
      $this->comments = $comments;
  }
}

class BlogPostComment
{
  private ?string $author = null;
  private ?string $text = null;

  // Comments can be left recursively
  private ?BlogPostCommentList $comments = null;

  public function getAuthor(): ?string
  {
      return $this->author;
  }

  public function setAuthor(?string $author): void
  {
      $this->author = $author;
  }

  public function getText(): ?string
  {
      return $this->text;
  }

  public function setText(?string $text): void
  {
      $this->text = $text;
  }

  public function getComments(): ?BlogPostCommentList
  {
      return $this->comments;
  }

  public function setComments(?BlogPostCommentList $comments): void
  {
      $this->comments = $comments;
  }
}

class BlogPostCommentList extends TypedList
{
  public function __construct()
  {
      parent::__construct(BlogPost::class);
  }
}
```

Readers of a post created using the above `BlogPost` structure can add `BlogPostComment` entries to the post's *comments* field,
and readers of these comments can reply with comments of their own, creating a recursive hierarchical structure.

For example, the following document, `BlogPosts/1-A`, represents a blog post by John that contains multiple layers of comments from various authors.

`BlogPosts/1-A`:

```json
{
  "Author": "John",
  "Title": "Post title..",
  "Text": "Post text..",
  "Comments": [
      {
          "Author": "Moon",
          "Text": "Comment text..",
          "Comments": [
              {
                  "Author": "Bob",
                  "Text": "Comment text.."
              },
              {
                  "Author": "Adel",
                  "Text": "Comment text..",
                  "Comments": {
                      "Author": "Moon",
                      "Text": "Comment text.."
                  }
              }
          ]
      }
  ],
  "@metadata": {
      "@collection": "BlogPosts"
  }
}
```

## Index hierarchical data

To index the elements of a hierarchical structure like the one above, use RavenDB's `Recurse` method.

The sample index below shows how to use `Recurse` to traverse the comments in the post thread and index them by their authors.
We can then [query the index](#query-the-index) for all blog posts that contain comments by specific authors.

### AbstractIndexCreationTask

```php
class BlogPosts_ByCommentAuthor_Result
{
  private ?StringArray $authors = null;

  public function getAuthors(): ?StringArray
  {
      return $this->authors;
  }

  public function setAuthors(?StringArray $authors): void
  {
      $this->authors = $authors;
  }
}

class BlogPosts_ByCommentAuthor extends AbstractIndexCreationTask
{
  public function __construct()
  {
      parent::__construct();

      $this->map = "from blogpost in docs.Blogposts let authors = Recurse(blogpost, x => x.comments) select new { authors = authors.Select(x => x.author) }";
  }
}
```

### Operation

```php
$indexDefinition = new IndexDefinition();
$indexDefinition->setName("BlogPosts/ByCommentAuthor");
$indexDefinition->setMaps([
  "from blogpost in docs.BlogPosts
  from comment in Recurse(blogpost, (Func<dynamic, dynamic>)(x => x.Comments))
  select new
  {
      Author = comment.Author
  }"
]);

$store->maintenance()->send(new PutIndexesOperation($indexDefinition));
```

## Query the index

The index can be queried for all blog posts that contain comments made by specific authors.

**Query the index using code**:

### Query

```php
/** @var array<BlogPost> $results */
$results = $session
  ->query(BlogPosts_ByCommentAuthor_Result::class, BlogPosts_ByCommentAuthor::class)
  ->whereEquals("authors", "john")
  ->ofType(BlogPost::class)
  ->toList();
```

### documentQuery

```php
/** @var array<BlogPost> $results */
$results = $session
      ->advanced()
      ->documentQuery(BlogPost::class, BlogPosts_ByCommentAuthor::class)
      ->whereEquals("authors", "John")
      ->toList();
```

### RQL

```sql
from index "BlogPosts/ByCommentAuthor"
where Authors == "Moon"
```

**Query the index using Studio**:

- Query the index from Studio's [List of Indexes](https://docs.ravendb.net/6.2/studio/database/indexes/indexes-list-view.md#indexes-list-view) view:

  !["List of Indexes view"](https://docs.ravendb.net/assets/images/list-of-indexes-view-0264fd76eb532b875ff987b54ac8b1a5.png)

- View the query results in the [Query](https://docs.ravendb.net/6.2/studio/database/queries/query-view.md) view:

  !["Query View"](https://docs.ravendb.net/assets/images/query-view-3bf9519c65639130153355e9601b0bfc.png)

- View the list of terms indexed by the `Recurse` method:

  !["Click to View Index Terms"](https://docs.ravendb.net/assets/images/click-to-view-terms-b3e9856139362596d1c7cc1bd99c5c34.png)

  !["Index Terms"](https://docs.ravendb.net/assets/images/index-terms-59dbac19292c26ef6b64fc4cb5c60512.png)

## See also

- [Indexing Basics](https://docs.ravendb.net/6.2/indexes/indexing-basics.md)
- [Indexing Related Documents](https://docs.ravendb.net/6.2/indexes/indexing-related-documents.php.md)
- [Indexing Spatial Data](https://docs.ravendb.net/6.2/indexes/indexing-spatial-data.php.md)
- [Indexing Polymorphic Data](https://docs.ravendb.net/6.2/indexes/indexing-polymorphic-data.php.md)
- [Basics](https://docs.ravendb.net/6.2/indexes/querying/query-index.php.md)
- [Query Overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.php.md)
