Best practices

Pagination

You can retrieve a limited number of items of a given type in a single query. This number is defined in the limit argument. It is currently set to 100 objects. Use paging to retrieve more than the number of items specified in the limit.

The Urban API provides offset-based pagination, in which a client requests a page based on an absolute index in the list (offset) and the maximum number of elements to return (limit).

Consider the following example to understand pagination: fetch all the projects from an urban model with more than 100 projects. This means that you cannot fetch all projects in one query.

Get the first 100 projects with the following query:

Use dark colors for code blocks
           
1
2
3
4
5
6
7
8
9
10
11
{
  urbanModel(urbanModelId: "61c6683e0ab645fdbc625c9XXXe3ac3e") {
    urbanDatabase {
      projects(paging: { limit: 100, offset: 0 }) {
        attributes {
          GlobalID
        }
      }
    }
  }
}

Note the paging argument added to projects. Change the offset argument from 0 to 100 (paging: { limit: 100, offset: 100 }) to retrieve the next 100 projects. Repeat changing the offset until all projects are fetched.

Splitting queries

GraphQL gives you the ability to fetch many resources in a single request. However, creating very deeply nested queries or asking for too many objects in a single query is not recommended because this may reduce performance. It can also lead to a situation where retrieving the correct data is more complicated than necessary.

Split your queries based on the number of items you expect in return. Make sure your queries are of a reasonable size.

Consider the following example: getting multiple types present in an urban model database: buildingTypes, overlayTypes, spaceUseTypes, and zoneTypes. You can do this in two different ways:

  • If you only need to retrieve fewer objects than specified by limit (see pagination), fetch all items with a single query:

    Use dark colors for code blocks
                                
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    {
      urbanModel(
        urbanModelId: "61c6683e0ab645fdbc625c9XXXe3ac3e"
      ) {
        urbanDatabase {
          buildingTypes {
            attributes {
              GlobalID
            }
          }
          overlayTypes {
            attributes {
              GlobalID
            }
          }
          spaceUseTypes {
            attributes {
              GlobalID
            }
          }
          zoneTypes {
            attributes {
              GlobalID
            }
          }
        }
      }
    }
  • If you need to retrieve more objects than limit, consider using separate queries for each type and use paging to fetch all desired results:

    Use dark colors for code blocks
                   
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    {
      urbanModel(
        urbanModelId: "61c6683e0ab645fdbc625c9XXXe3ac3e"
      ) {
        urbanDatabase {
          buildingTypes(
            paging: { limit: 100, offset: 0 }
          ) {
            attributes {
              GlobalID
            }
          }
        }
      }
    }

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.