1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.datastore.v1; 18 19import "google/protobuf/struct.proto"; 20import "google/protobuf/timestamp.proto"; 21import "google/type/latlng.proto"; 22 23option csharp_namespace = "Google.Cloud.Datastore.V1"; 24option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore"; 25option java_multiple_files = true; 26option java_outer_classname = "EntityProto"; 27option java_package = "com.google.datastore.v1"; 28option php_namespace = "Google\\Cloud\\Datastore\\V1"; 29option ruby_package = "Google::Cloud::Datastore::V1"; 30 31// A partition ID identifies a grouping of entities. The grouping is always 32// by project and namespace, however the namespace ID may be empty. 33// 34// A partition ID contains several dimensions: 35// project ID and namespace ID. 36// 37// Partition dimensions: 38// 39// - May be `""`. 40// - Must be valid UTF-8 bytes. 41// - Must have values that match regex `[A-Za-z\d\.\-_]{1,100}` 42// If the value of any dimension matches regex `__.*__`, the partition is 43// reserved/read-only. 44// A reserved/read-only partition ID is forbidden in certain documented 45// contexts. 46// 47// Foreign partition IDs (in which the project ID does 48// not match the context project ID ) are discouraged. 49// Reads and writes of foreign partition IDs may fail if the project is not in 50// an active state. 51message PartitionId { 52 // The ID of the project to which the entities belong. 53 string project_id = 2; 54 55 // If not empty, the ID of the database to which the entities 56 // belong. 57 string database_id = 3; 58 59 // If not empty, the ID of the namespace to which the entities belong. 60 string namespace_id = 4; 61} 62 63// A unique identifier for an entity. 64// If a key's partition ID or any of its path kinds or names are 65// reserved/read-only, the key is reserved/read-only. 66// A reserved/read-only key is forbidden in certain documented contexts. 67message Key { 68 // A (kind, ID/name) pair used to construct a key path. 69 // 70 // If either name or ID is set, the element is complete. 71 // If neither is set, the element is incomplete. 72 message PathElement { 73 // The kind of the entity. 74 // 75 // A kind matching regex `__.*__` is reserved/read-only. 76 // A kind must not contain more than 1500 bytes when UTF-8 encoded. 77 // Cannot be `""`. 78 // 79 // Must be valid UTF-8 bytes. Legacy values that are not valid UTF-8 are 80 // encoded as `__bytes<X>__` where `<X>` is the base-64 encoding of the 81 // bytes. 82 string kind = 1; 83 84 // The type of ID. 85 oneof id_type { 86 // The auto-allocated ID of the entity. 87 // 88 // Never equal to zero. Values less than zero are discouraged and may not 89 // be supported in the future. 90 int64 id = 2; 91 92 // The name of the entity. 93 // 94 // A name matching regex `__.*__` is reserved/read-only. 95 // A name must not be more than 1500 bytes when UTF-8 encoded. 96 // Cannot be `""`. 97 // 98 // Must be valid UTF-8 bytes. Legacy values that are not valid UTF-8 are 99 // encoded as `__bytes<X>__` where `<X>` is the base-64 encoding of the 100 // bytes. 101 string name = 3; 102 } 103 } 104 105 // Entities are partitioned into subsets, currently identified by a project 106 // ID and namespace ID. 107 // Queries are scoped to a single partition. 108 PartitionId partition_id = 1; 109 110 // The entity path. 111 // An entity path consists of one or more elements composed of a kind and a 112 // string or numerical identifier, which identify entities. The first 113 // element identifies a _root entity_, the second element identifies 114 // a _child_ of the root entity, the third element identifies a child of the 115 // second entity, and so forth. The entities identified by all prefixes of 116 // the path are called the element's _ancestors_. 117 // 118 // An entity path is always fully complete: *all* of the entity's ancestors 119 // are required to be in the path along with the entity identifier itself. 120 // The only exception is that in some documented cases, the identifier in the 121 // last path element (for the entity) itself may be omitted. For example, 122 // the last path element of the key of `Mutation.insert` may have no 123 // identifier. 124 // 125 // A path can never be empty, and a path can have at most 100 elements. 126 repeated PathElement path = 2; 127} 128 129// An array value. 130message ArrayValue { 131 // Values in the array. 132 // The order of values in an array is preserved as long as all values have 133 // identical settings for 'exclude_from_indexes'. 134 repeated Value values = 1; 135} 136 137// A message that can hold any of the supported value types and associated 138// metadata. 139message Value { 140 // Must have a value set. 141 oneof value_type { 142 // A null value. 143 google.protobuf.NullValue null_value = 11; 144 145 // A boolean value. 146 bool boolean_value = 1; 147 148 // An integer value. 149 int64 integer_value = 2; 150 151 // A double value. 152 double double_value = 3; 153 154 // A timestamp value. 155 // When stored in the Datastore, precise only to microseconds; 156 // any additional precision is rounded down. 157 google.protobuf.Timestamp timestamp_value = 10; 158 159 // A key value. 160 Key key_value = 5; 161 162 // A UTF-8 encoded string value. 163 // When `exclude_from_indexes` is false (it is indexed) , may have at most 164 // 1500 bytes. Otherwise, may be set to at most 1,000,000 bytes. 165 string string_value = 17; 166 167 // A blob value. 168 // May have at most 1,000,000 bytes. 169 // When `exclude_from_indexes` is false, may have at most 1500 bytes. 170 // In JSON requests, must be base64-encoded. 171 bytes blob_value = 18; 172 173 // A geo point value representing a point on the surface of Earth. 174 google.type.LatLng geo_point_value = 8; 175 176 // An entity value. 177 // 178 // - May have no key. 179 // - May have a key with an incomplete key path. 180 // - May have a reserved/read-only key. 181 Entity entity_value = 6; 182 183 // An array value. 184 // Cannot contain another array value. 185 // A `Value` instance that sets field `array_value` must not set fields 186 // `meaning` or `exclude_from_indexes`. 187 ArrayValue array_value = 9; 188 } 189 190 // The `meaning` field should only be populated for backwards compatibility. 191 int32 meaning = 14; 192 193 // If the value should be excluded from all indexes including those defined 194 // explicitly. 195 bool exclude_from_indexes = 19; 196} 197 198// A Datastore data object. 199// 200// Must not exceed 1 MiB - 4 bytes. 201message Entity { 202 // The entity's key. 203 // 204 // An entity must have a key, unless otherwise documented (for example, 205 // an entity in `Value.entity_value` may have no key). 206 // An entity's kind is its key path's last element's kind, 207 // or null if it has no key. 208 Key key = 1; 209 210 // The entity's properties. 211 // The map's keys are property names. 212 // A property name matching regex `__.*__` is reserved. 213 // A reserved property name is forbidden in certain documented contexts. 214 // The map keys, represented as UTF-8, must not exceed 1,500 bytes and cannot 215 // be empty. 216 map<string, Value> properties = 3; 217} 218