Files - Cognite Docs

Legacy data modeling

This resource is part of the asset-centric data model.

New projects: We recommend using the data modeling service for greater flexibility and performance.
Existing projects: This resource remains fully supported for maintaining legacy applications.

Looking for file upload/download? See File content for uploading and downloading files.This page focuses on file metadata management for asset-centric projects.

The files API lets you create, update, search, and manage file metadata in asset-centric projects. For data modeling projects, use the Instances API to manage files as instances in your data model. Files in CDF can be related to one or more assets. For example, a file can contain a piping and instrumentation diagram (P&ID) that shows how several assets connect. Each file has a unique id generated at file creation. Specify a fileName when the file is created. If you want to be in control of the file identifier, you can specify an externalId which must be unique within a project. A file can also have metadata key-value fields that are searchable. You can use these fields to store source system IDs and other information. Additionally, files can have labels attached to them, making it easier to organize and categorize files.

Geographic location of files

Specify a file’s geographic location, for example, its geometric features and coordinates, in the geoLocation field. Data in this field needs to follow the GeoJSON specification, explained in detail in RFC 7946. The coordinate reference system for all GeoJSON coordinates is a geographic coordinate reference system that uses the World Geodetic System 1984 (WGS84).

GeoJSON types

A GeoJSON object has one of 3 types:

Feature - Geometric objects with (optional) extra features.
FeatureCollection - A collection of Features.
GeometryCollection - A collection of Geometry objects (see below).

Currently, Feature is the only type supported by CDF. To describe a geographic feature, the Geometry object needs a type and a corresponding array of coordinates. Below are the supported Geometry types:

Type	Description
Point	Only one exact point.	`{"type": "Point", "coordinates": [30, 10]}`
MultiPoint	Multiple points.	`{"type": "MultiPoint", "coordinates": [[10, 40], [40, 30], [20, 20], [30, 10]]}`
LineString	A line.	`{"type": "LineString", "coordinates": [[30, 10], [10, 30], [40, 40]]}`
MultiLineString	Multiple lines.	`{"type": "MultiLineString", "coordinates": [[[10, 10], [20, 20], [10, 40]], [[40, 40], [30, 30], [40, 20], [30, 10]]]}`
Polygon	A closed shape. Can have inner holes of arbitrary shapes.	`{"type": "Polygon", "coordinates": [[[35, 10], [45, 45], [15, 40], [10, 20], [35, 10]], [[20, 30], [35, 35], [30, 20], [20, 30]]]}`
MultiPolygon	Multiple closed shapes. Can have inner holes of arbitrary shapes.	`{"type": "MultiPolygon", "coordinates": [[[[30, 20], [45, 40], [10, 40], [30, 20]]], [[[15, 5], [40, 10], [10, 20], [5, 10], [15, 5]]]]}`

Adding geoLocation to a file

The geoLocation field requires the following properties:

type

The type of GeoJSON. CDF only supports the Feature type.

geometry

Represents the points, curves, and surfaces in coordinate space. The property consists of:

type - Must be one of the following geometry types: Point, MultiPoint, LineString, MultiLineString, Polygon, and MultiPolygon. See GeoJSON types above.
coordinates - An array describing the specified geometry type. The type of geometry determines the shape of this array. For instance, a Point geometry type will contain a coordinate array consisting of just a single x and a single y coordinate. See example 1 below.
A LineString geometry type will contain a coordinate array with two or more points, as shown in example 2. A Polygon geometry type will need to contain an array of closed LineStrings with four or more points, as shown in example 3. See the GeoJSON spec for more details on the various shapes of the coordinates field.

properties

An optional field specifying extra information to enrich the Feature. Example 1

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [10.727414488792418, 6059.91713955864316]
  },
  "properties": {
    "name": "Norwegian Royal Palace"
  }
}

Example 2

{
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [35, 10],
      [45, 45],
      [15, 40],
      [10, 20],
      [35, 10]
    ]
  }
}

Example 3 Note that in this example, the Polygon specifies an outer and inner LineString. A Polygon can (but doesn’t have to) contain several of these LineStrings, where the first must be the exterior ring, and the next LineStrings are interior rings. This is how you would define a surface with holes.

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [35, 10],
        [45, 45],
        [15, 40],
        [10, 20],
        [35, 10]
      ],
      [
        [20, 30],
        [35, 35],
        [30, 20],
        [20, 30]
      ]
    ]
  }
}

Upload example

POST /api/v1/projects/publicdata/files
Content-Type: application/json

{
  "name": "file1",
  "externalId": "file",
  "geoLocation": {
    "type": "Feature",
    "geometry": {
      "type": "point",
      "coordinates": [
        10.727414488792418,
        6059.91713955864316
      ]
    },
    "properties": {
      "name": "Norwegian Royal Palace"
    }
  }
}

Update example

POST /api/v1/projects/publicdata/files/update
Content-Type: application/json

{
  "items": [
    {
      "id": 123454321,
      "update": {
        "geoLocation": {
          "set": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                133.2,
                2.5
              ]
            },
            "properties": {
              "name": "Another place"
            }
          }
        }
      }
    }
  ]
}

GeoLocation filtering

Filtering on, or searching for files matching a certain geoLocation requires two properties:

relation - The geographic relation, either INTERSECTS, WITHIN, or DISJOINT.
shape - The geometry, as described in the geometry section. Filtering is not available for the MultiPoint type.

Filter example

POST /api/v1/projects/publicdata/files/list
Content-Type: application/json

{
   "filter": {
       "geoLocation": {
         "relation": "intersects",
         "shape": {
           "type": "MultiPolygon",
           "coordinates": [[
            [[35, 10], [45, 45], [15, 40], [10, 20], [35, 10]],
            [[20, 30], [35, 35], [30, 20], [20, 30]]
            ], [
          [[36, 11], [46, 46], [16, 41], [11, 21], [36, 11]],
          [[21, 31], [36, 36], [31, 21], [21, 31]]
          ]]
         }
       }

   }
}

Rate and concurrency limits

For Files rate and concurrency limits, see API rate limits.

API reference (20230101)

​Geographic location of files

​GeoJSON types

​Adding geoLocation to a file

​type

​geometry

​properties

​Upload example

​Update example

​GeoLocation filtering

​Filter example

​Rate and concurrency limits

Geographic location of files

GeoJSON types

Adding geoLocation to a file

type

geometry

properties

Upload example

Update example

GeoLocation filtering

Filter example

Rate and concurrency limits