---
updatedAt: 2026-01-19T20:59:39.000Z
agentTools:
  projectIndex: https://changelog-dzt-kg.readme.io/llms.txt
---

# Fetching Big Objects Iteratively

<Callout icon="❗️" theme="error">
  **Note:** This is the recommended way of fetching data!
</Callout>

The more data the Knowledge Graph holds and the better the data is linked, the more careful a user must be when fetching an object.

Imagine a dataset about a tour with some properties, say, `name`, `description`, `image`, `startLocation` and an `endLocation`.  That's not an extraordinarily expressive data set, but it can already lead to some interesting side effects because of the graph form in which data is stored. Imagine the `startLocation` is not just a string or an object with a city name or geo coordinates, but maybe it's a point of interest (POI) that is itself stored in the graph. Maybe this POI has dozens of properties with complex nested data objects. A query now asks for the tour without specifying how "deep" the graph should be traversed; it might try to return Megabytes of data.

There are, of course, ways to deal with that, which we will explain in the following. Summarizing:

1. us the `hop`parameter (<=2)
2. fetch the data iteratively.

# 1. The `hop` parameter

The API supports a header parameter which is called `x-hop` (in this article, we just call it `hop`) (It is also described in Section [Retrieving Objects](https://onlimgmbh.atlassian.net/browse/DZTSUP-181)). A *hop* is meant as one level of *depth* in the nesting of an object. In the tour example from above, a hop=1 would return all first-level properties of the tour: `name`, `description`, `image`, `startLocation` and `endLocation`. However, it would only return the real values for properties with primitive ranges, such as string, number or date. For ranges that are objects, like `startLocation` and `endLocation`, the query would return a URI. This URI is the root node of a sub-graph and can be queried. A hop of 2 would respond with the first-level properties of `startLocation` and `endLocation` and the query is fine as long as that's about it. A hop of 3 would time out in most of the cases.

# 2. Iterative data retrieval

If we need to fetch data which is nested deeper, say something like Tour.startLocation.containesPlace.menu.mainDishes.ingredients, then this needs to be done one object at a time.

First, a call would fetch the first-level properties with a `hop=1`. If the value of a property is not a string (or alike) but an object containing nothing but an `@id` property, then a second call is required - again with`hop=1`.

# 3. Example

**Example**: a Hotel called "Hotel Restaurant Pelikan"\
**URL of the data set**: <https://mein.toubiz.de/api/v1/article/ab9248cb-45f9-41a7-a45c-9c3e38aac6d2>

The api call to fetch the object, without a hop definition, times out. The correct call looks like this:

```asp VSCode Rest Client
GET https://proxy.opendatagermany.io/api/ts/v1/kg/things/ab9248cb-45f9-41a7-a45c-9c3e38aac6d2?lang=de&ns=https://mein.toubiz.de/api/v1/article
x-api-key: <api-key>
Content-Type: application/json
x-hop: 1
```

(To learn how the query is built, read [Retrieving objects](https://changelog-dzt-kg.readme.io/docs/retrieving-objects#optimisations-x-hop-and-iterative-loading-of-nested-objects))

The (full) response looks like this:

```json
[
  {
    "@id": "https://mein.toubiz.de/api/v1/article/ab9248cb-45f9-41a7-a45c-9c3e38aac6d2",
    "@type": [
      "https://schema.org/Hotel",
      "https://schema.org/LodgingBusiness",
      "https://schema.org/HotelRoom"
    ],
    "https://odta.io/voc/geoLink": [
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_2fa4bbec-ec4c-4f11-acc5-b349bebc7178"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_57c4e466-9fa7-43b9-87e7-6321faea22fe"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_91e08de1-59b7-45d8-adbe-7ee74022a5f9"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_06af03f4-2c71-4592-834f-63f487eb7a28"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_d8803ffd-b658-4f0a-9454-b509f168d74e"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_1eb33ce1-3492-43c0-8de4-8130e293eb6f"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_c718ce93-09d9-4587-bdf3-0af939f46360"
      },
      {
        "@id": "http://onlim.com/entity/geoEnrichmentID_14044074-2fc2-4205-9ae9-18fcc9ca26d7"
      }
    ],
    "https://schema.org/address": {
      "@id": "http://onlim.com/entity/ea0941cd-7f14-4cbc-8a37-8ad03612029c"
    },
    "https://schema.org/containedInPlace": {
      "@id": "https://gdz.bkg.bund.de/Gebietseinheiten/rg/L60"
    },
    "https://schema.org/geo": {
      "@id": "http://onlim.com/entity/d3f5ac81-d7f4-40b0-a8cc-87bc07630c86"
    },
    "https://schema.org/hasMap": {
      "@type": "http://www.w3.org/2001/XMLSchema#anyURI",
      "@value": "https://w3w.co/bahnsteigen.zufrieden.anf%C3%BChren"
    },
    "https://schema.org/identifier": {
      "@type": "http://www.w3.org/2001/XMLSchema#anyURI",
      "@value": "https://mein.toubiz.de/api/v1/article/ab9248cb-45f9-41a7-a45c-9c3e38aac6d2"
    },
    "https://schema.org/isAccessibleForFree": {
      "@type": "http://www.w3.org/2001/XMLSchema#boolean",
      "@value": "false"
    },
    "https://schema.org/name": {
      "@language": "de",
      "@value": "Hotel Restaurant Pelikan"
    },
    "https://schema.org/sdLicense": {
      "@type": "http://www.w3.org/2001/XMLSchema#anyURI",
      "@value": "https://creativecommons.org/licenses/by-sa/4.0/"
    },
    "https://schema.org/telephone": "+49 7466 910000",
    "https://schema.org/url": {
      "@type": "http://www.w3.org/2001/XMLSchema#anyURI",
      "@value": "https://pelikanhotel.de"
    },
    "https://vocab.sti2.at/ds/compliesWith": {
      "@id": "https://semantify.it/ds/gGDiyXWKpGpu"
    }
  }
]

```

As you can see, there is already some first-level information materialized:

* `schema:hasMap`: line 45
* `schema:name`: line 57
* `schema:sdLicense`: line 61
* `schema:telephone`: line 65
* ...

But maybe you are interested in the postal address, linked locations or the geo coordinates? Then, use a second call for it (theoretically, for `schema:postalAddress` or `schema:geo` a call with hop 2 would work, but better safe than sorry). To perform that call, just use the URI (the `@id` property of the object), as a new identifier. In the example below, let's fetch the geolocation of the hotel (line 42: `schema:geo`):

**URI:** <http://onlim.com/entity/d3f5ac81-d7f4-40b0-a8cc-87bc07630c86>

Call:

```asp VSCode Rest Client
GET https://proxy.opendatagermany.io/api/ts/v1/kg/things/d3f5ac81-d7f4-40b0-a8cc-87bc07630c86?lang=de&ns=http://onlim.com/entity
x-api-key: <api-key>
Content-Type: application/json
X-HOP: 1
```

The response looks like this:

```json
[
  {
    "@id": "http://onlim.com/entity/d3f5ac81-d7f4-40b0-a8cc-87bc07630c86",
    "@type": "https://schema.org/GeoCoordinates",
    "https://schema.org/latitude": {
      "@type": "http://www.w3.org/2001/XMLSchema#double",
      "@value": "48.0506835"
    },
    "https://schema.org/longitude": {
      "@type": "http://www.w3.org/2001/XMLSchema#double",
      "@value": "8.9701657"
    },
    "https://vocab.sti2.at/ds/compliesWith": {
      "@id": "https://semantify.it/ds/ZsYjkGgoQgxo"
    }
  }
]
```

<br />

## Note: "programmatic condition"

The (programmatic) decision, whether to try to dig deeper (to do more iterations) or not, can be made based on the presence of an `@id` property. If there is an `@id` property, this means a nested object is referenced and not materialized.

```json
 "https://schema.org/geo": {
   "@id": "http://onlim.com/entity/d3f5ac81-d7f4-40b0-a8cc-87bc07630c86"
 },
```