Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ישויות, מאפיינים ומפתחות

אובייקטים של נתונים ב-Firestore במצב Datastore נקראים ישויות. לישות יש מאפיין אחד או יותר עם שם, ולכל מאפיין יכול להיות ערך אחד או יותר. לישויות מאותו סוג לא צריכים להיות אותם מאפיינים, וערכי המאפיינים של ישות מסוימת לא צריכים להיות מאותו סוג נתונים. (במקרה הצורך, אפליקציה יכולה להגדיר ולאכוף הגבלות כאלה במודל הנתונים שלה).

במצב Datastore יש מגוון סוגי נתונים לערכי מאפיינים. לדוגמה:

מספרים שלמים
מספרים בשיטת נקודה צפה
מחרוזות
תאריכים
נתונים בינאריים

לכל ישות במסד נתונים במצב Datastore יש מפתח שמזהה אותה באופן ייחודי. המפתח מורכב מהרכיבים הבאים:

מרחב השמות של הישות, שמאפשר ריבוי דיירים
סוג הישות, שמסווג אותה לצורך שאילתות
מזהה של הישות הספציפית, שיכול להיות אחד מהבאים:
- מחרוזת שם המפתח
- מזהה מספרי שהוא מספר שלם
ancestor path אופציונלי שמציין את מיקום הישות בהיררכיית מסד הנתונים

אפליקציה יכולה לאחזר ישות בודדת ממסד הנתונים באמצעות המפתח של הישות, או לאחזר ישות אחת או יותר באמצעות שאילתה שמבוססת על המפתחות או על ערכי המאפיינים של הישויות.

מערכת Firestore במצב Datastore לא אוכפת מגבלות על מבנה הישויות, למשל אם למאפיין מסוים יש ערך מסוג מסוים. המשימה הזו מוטלת על האפליקציה.

הקטעים בדף הזה מבוססים על הדוגמה שבמאמר תחילת העבודה עם Firestore במצב Datastore.

עבודה עם ישויות

אפליקציות יכולות להשתמש ב-Firestore ב-Datastore mode API כדי ליצור, לאחזר, לעדכן ולמחוק ישויות. אם האפליקציה יודעת את המפתח המלא של ישות (או יכולה לגזור אותו ממפתח האב, הסוג והמזהה שלה), היא יכולה להשתמש במפתח כדי לפעול ישירות על הישות. אפליקציה יכולה גם לקבל את המפתח של ישות כתוצאה משאילתה. מידע נוסף זמין בנושא שאילתות.

יצירת ישות

כדי ליצור ישות חדשה, מאתחלים אותה ומגדירים את המאפיינים שלה:

C#

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore C# API.

כדי לבצע אימות ב-Cloud Datastore, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["done"] = false,
    ["priority"] = 4,
    ["description"] = "Learn Cloud Datastore"
};

Go

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore Go API.

type Task struct {
	Category        string
	Done            bool
	Priority        float64
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore Java API.

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");
Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();

Node.js

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore Node.js API.

const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

PHP

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore PHP API.

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);

Python

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore Python API.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task = datastore.Entity(client.key("Task"))
task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

Ruby

מידע על התקנת ספריית הלקוח של Cloud Datastore ושימוש בה מופיע במאמר ספריות הלקוח של Cloud Datastore. מידע נוסף מופיע במאמרי העזרה של Cloud Datastore Ruby API.

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

אפשר לשמור את הישות במסד הנתונים באמצעות upsert (שיחליף ישות אם היא כבר קיימת במצב Datastore) או insert (שדורש שמפתח הישות לא יהיה קיים).

כך upsert ישות:

C#

_db.Upsert(_sampleTask);

Go

key := datastore.IncompleteKey("Task", nil)
key, err := client.Put(ctx, key, task)

Java

Entity task = Entity.newBuilder(keyFactory.newKey("sampleTask")).build();
datastore.put(task);

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.upsert(entity);
// Task inserted successfully.

PHP

$key = $datastore->key('Task', 'sampleTask');
$task = $datastore->entity($key, [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->upsert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

complete_key = client.key("Task", "sampleTask")

task = datastore.Entity(key=complete_key)

task.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

client.put(task)

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end
datastore.save task

כך insert ישות:

C#

Entity task = new Entity()
{
    Key = _keyFactory.CreateIncompleteKey()
};
task.Key = _db.Insert(task);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
_, err := client.RunInTransaction(ctx, func(tx *datastore.Transaction) error {
	// We first check that there is no entity stored with the given key.
	var empty Task
	if err := tx.Get(taskKey, &empty); err != datastore.ErrNoSuchEntity {
		return err
	}
	// If there was no matching entity, store it now.
	_, err := tx.Put(taskKey, &task)
	return err
})

Java

Key taskKey = datastore.add(FullEntity.newBuilder(keyFactory.newKey()).build()).getKey();

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

datastore.insert(entity).then(() => {
  // Task inserted successfully.
});

PHP

$task = $datastore->entity('Task', [
    'category' => 'Personal',
    'done' => false,
    'priority' => 4,
    'description' => 'Learn Cloud Datastore'
]);
$datastore->insert($task);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    incomplete_key = client.key("Task")

    task = datastore.Entity(key=incomplete_key)

    task.update(
        {
            "category": "Personal",
            "done": False,
            "priority": 4,
            "description": "Learn Cloud Datastore",
        }
    )

    client.put(task)

Ruby

datastore.transaction do |_tx|
  task = datastore.entity "Task" do |t|
    t["category"] = "Personal"
    t["done"] = false
    t["priority"] = 4
    t["description"] = "Learn Cloud Datastore"
  end
  datastore.save task
end

אחזור ישות

כדי לאחזר ישות ממסד הנתונים, משתמשים במפתח שלה לחיפוש:

C#

Entity task = _db.Lookup(_sampleTask.Key);

Go

var task Task
taskKey := datastore.NameKey("Task", "sampleTask", nil)
err := client.Get(ctx, taskKey, &task)

Java

Entity task = datastore.get(taskKey);

Node.js

const taskKey = datastore.key('Task');
const [entity] = await datastore.get(taskKey);
// entity = {
//   category: 'Personal',
//   done: false,
//   priority: 4,
//   description: 'Learn Cloud Datastore',
//   [Symbol(KEY)]:
//    Key {
//      namespace: undefined,
//      id: '...',
//      kind: 'Task',
//      path: [Getter]
//    }
//   }
// };
console.log(entity);

PHP

$task = $datastore->lookup($key);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
task = client.get(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
task = datastore.find task_key

עדכון ישות

כדי update ישות קיימת, משנים את המאפיינים של הישות שאוחזרה קודם ומאחסנים אותה באמצעות המפתח:

C#

_sampleTask["priority"] = 5;
_db.Update(_sampleTask);

Go

taskKey := datastore.NameKey("Task", "sampleTask", nil)
tx, err := client.NewTransaction(ctx)
if err != nil {
	log.Fatalf("client.NewTransaction: %v", err)
}
var task Task
if err := tx.Get(taskKey, &task); err != nil {
	log.Fatalf("tx.Get: %v", err)
}
task.Priority = 5
if _, err := tx.Put(taskKey, &task); err != nil {
	log.Fatalf("tx.Put: %v", err)
}
if _, err := tx.Commit(); err != nil {
	log.Fatalf("tx.Commit: %v", err)
}

Java

Entity task;
Transaction txn = datastore.newTransaction();
try {
  task = Entity.newBuilder(txn.get(taskKey)).set("priority", 5).build();
  txn.put(task);
  txn.commit();
} finally {
  if (txn.isActive()) {
    txn.rollback();
  }
}

Node.js

const taskKey = datastore.key('Task');
const task = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const entity = {
  key: taskKey,
  data: task,
};

await datastore.update(entity);
// Task updated successfully.

PHP

$transaction = $datastore->transaction();
$key = $datastore->key('Task', 'sampleTask');
$task = $transaction->lookup($key);
$task['priority'] = 5;
$transaction->update($task);
$transaction->commit();

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

with client.transaction():
    key = client.key("Task", "sampleTask")
    task = client.get(key)

    task["done"] = True

    client.put(task)

Ruby

# task_name = "sampleTask"
datastore.transaction do |_tx|
  task = datastore.find "Task", task_name
  task["priority"] = 5
  datastore.save task
end

הנתונים שסופקו מחליפים את הישות הקיימת. צריך לשלוח את האובייקט כולו למסד הנתונים. אם הישות לא קיימת, העדכון ייכשל. כדי לעדכן או ליצור ישות, משתמשים ב-upsert כמו שמתואר למעלה. שימוש בטרנזקציה מאפשר לבצע את הפעולות get ו-update בטרנזקציה אטומית אחת.

מחיקת ישות

בהינתן המפתח של ישות, אפשר delete את הישות:

C#

_db.Delete(_sampleTask.Key);

Go

key := datastore.NameKey("Task", "sampletask", nil)
err := client.Delete(ctx, key)

Java

datastore.delete(taskKey);

Node.js

const taskKey = datastore.key('Task');
await datastore.delete(taskKey);
// Task deleted successfully.

PHP

$datastore->delete($taskKey);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")
client.delete(key)

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name
datastore.delete task_key

פעולות באצווה

‫Firestore במצב Datastore תומך בגרסאות אצווה של הפעולות, שמאפשרות לו לפעול על כמה אובייקטים בקריאה אחת של מצב Datastore.

הקריאות האלה לקבוצות קבצים מהירות יותר מקריאות נפרדות לכל ישות בנפרד, כי הן כרוכות בתקורה של קריאה אחת בלבד לשירות. אם יש כמה קבוצות ישויות, העבודה של כל הקבוצות מתבצעת במקביל בצד השרת.

לדוגמה, אפשר upsert כמה ישויות:

C#

var taskList = new[]
{
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = false,
        ["priority"] = 4,
        ["description"] = "Learn Cloud Datastore"
    },
    new Entity()
    {
        Key = _keyFactory.CreateIncompleteKey(),
        ["category"] = "Personal",
        ["done"] = "false",
        ["priority"] = 5,
        ["description"] = "Integrate Cloud Datastore"
    }
};
var keyList = _db.Upsert(taskList[0], taskList[1]);

Go

tasks := []*Task{
	{
		Category:    "Personal",
		Done:        false,
		Priority:    4,
		Description: "Learn Cloud Datastore",
	},
	{
		Category:    "Personal",
		Done:        false,
		Priority:    5,
		Description: "Integrate Cloud Datastore",
	},
}
keys := []*datastore.Key{
	datastore.IncompleteKey("Task", nil),
	datastore.IncompleteKey("Task", nil),
}

keys, err := client.PutMulti(ctx, keys, tasks)

Java

FullEntity<IncompleteKey> task1 =
    FullEntity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 4)
        .set("description", "Learn Cloud Datastore")
        .build();
FullEntity<IncompleteKey> task2 =
    Entity.newBuilder(keyFactory.newKey())
        .set("category", "Personal")
        .set("done", false)
        .set("priority", 5)
        .set("description", "Integrate Cloud Datastore")
        .build();
List<Entity> tasks = datastore.add(task1, task2);
Key taskKey1 = tasks.get(0).getKey();
Key taskKey2 = tasks.get(1).getKey();

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const task1 = {
  category: 'Personal',
  done: false,
  priority: 4,
  description: 'Learn Cloud Datastore',
};

const task2 = {
  category: 'Work',
  done: false,
  priority: 8,
  description: 'Integrate Cloud Datastore',
};

const entities = [
  {
    key: taskKey1,
    data: task1,
  },
  {
    key: taskKey2,
    data: task2,
  },
];

await datastore.upsert(entities);
// Tasks inserted successfully.

PHP

$result = $datastore->upsertBatch($tasks);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

task1 = datastore.Entity(client.key("Task", 1))

task1.update(
    {
        "category": "Personal",
        "done": False,
        "priority": 4,
        "description": "Learn Cloud Datastore",
    }
)

task2 = datastore.Entity(client.key("Task", 2))

task2.update(
    {
        "category": "Work",
        "done": False,
        "priority": 8,
        "description": "Integrate Cloud Datastore",
    }
)

client.put_multi([task1, task2])

Ruby

task_1 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

task_2 = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

tasks = datastore.save task_1, task_2
task_key_1 = tasks[0].key
task_key_2 = tasks[1].key

אפשר לחפש כמה ישויות:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
var tasks = _db.Lookup(keys[0], keys[1]);

Go

var taskKeys []*datastore.Key // Populated with incomplete keys.
tasks := make([]*Task, len(taskKeys))
err := client.GetMulti(ctx, taskKeys, &tasks)

Java

Iterator<Entity> tasks = datastore.get(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

const [tasks] = await datastore.get(keys);
// Tasks retrieved successfully.
console.log(tasks);

PHP

$result = $datastore->lookupBatch($keys);
if (isset($result['found'])) {
    // $result['found'] is an array of entities.
} else {
    // No entities found.
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
tasks = client.get_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
tasks = datastore.find_all task_key_1, task_key_2

אפשר למחוק כמה ישויות:

C#

var keys = new Key[] { _keyFactory.CreateKey(1), _keyFactory.CreateKey(2) };
_db.Delete(keys);

Go

err := client.DeleteMulti(ctx, taskKeys)

Java

datastore.delete(taskKey1, taskKey2);

Node.js

const taskKey1 = this.datastore.key(['Task', 1]);
const taskKey2 = this.datastore.key(['Task', 2]);

const keys = [taskKey1, taskKey2];

await datastore.delete(keys);
// Tasks deleted successfully.

PHP

$result = $datastore->deleteBatch($keys);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

keys = [client.key("Task", 1), client.key("Task", 2)]
client.delete_multi(keys)

Ruby

# task_name_1 = "sampleTask1"
# task_name_2 = "sampleTask2"
task_key_1 = datastore.key "Task", task_name_1
task_key_2 = datastore.key "Task", task_name_2
datastore.delete task_key_1, task_key_2

פעולות אצווה לא משנות את עלויות הקריאה, הכתיבה או המחיקה, שמפורטות במאמר תמחור ומכסות. תחויבו על כל מפתח בפעולה שכוללת כמה מפתחות, גם אם המפתח לא קיים.

הגודל של הישויות שמעורבות בפעולה לא משפיע על עלויות הקריאה, הכתיבה או המחיקה. עם זאת, הגודל של הישויות משפיע על העלויות של נפח האחסון.

הגדלה של ערך מאפיין ושינויים אחרים במאפיינים

אפשר להשתמש בהמרות של נכסים כמו increment כדי לבצע עדכונים בצד השרת בנכס. השימוש בשינוי מאפיין חוסך פעולת קריאה נוספת בצד הלקוח כדי לקבל את הערך הנוכחי, וחישוב בצד הלקוח כדי לקבוע את הערך החדש.

מצב Datastore תומך בהמרות המאפיינים הבאות:

increment
maximum
minimum
appendMissingElements
removeAllFromArray
setToServerValue(REQUEST_TIME)

בדוגמה הבאה מוצג שינוי של מאפיין. הפעולה הזו מגדילה את ערכי המאפיינים לפי הערכים שצוינו:

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "quantity",
          "increment": {
            "integerValue": 2
          }
        },
        {
          "property": "inStock",
          "maximum": {
            "integerValue": 100
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Items",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

בדוגמה הבאה מוגדר ערך מאפיין לזמן שבו השרת עיבד את הבקשה, ברמת דיוק של אלפיות השנייה.

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "timeField",
          "setToServerValue": "REQUEST_TIME"
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

בדוגמה הבאה, אם חסרים רכיבים במערך, הם מתווספים.

REST

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {},  // Empty write mask indicates only transforms can change the entity.
      "propertyTransforms": [
        {
          "property": "arrayField",
          "appendMissingElements": {
            "values": [
              { "stringValue": "str" }, { "integerValue": 10 }
            ]
          }
        },
      ]
      "upsert": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
      }
    }
  ]
}

סוגים מעורבים עם `maximum` ועם `minimum`

הערך של מאפייני ההמרה maximum ו-minimum יכול להיות מספר שלם או מספר ממשי (מספר עם נקודה צפה (floating-point)). הערך במאפיין היעד יכול להיות גם מספר שלם או מספר עשרוני.

אם המאפיין הוא לא מספר שלם או מספר עשרוני, או אם המאפיין לא קיים, הפונקציה להמרת נתונים מגדירה את המאפיין לערך ולסוג הקלט שצוינו. אם מוחלת פעולת maximum שבה המאפיין וערך הקלט הם מסוגים מעורבים (כלומר, אחד הוא מספר שלם ואחד הוא מספר עשרוני), המאפיין מקבל את הסוג של האופרנד הגדול יותר. במקרה של minimum, המאפיין מקבל את הסוג של האופרנד הקטן יותר.

אם האופרנדים שווים (למשל 3 ו-3.0), המאפיין לא משתנה. ‫0, 0.0 ו-‎-0.0 הם אפס. הערך maximum או minimum של ערך מאוחסן אפס וערך קלט אפס הוא תמיד הערך המאוחסן. התוצאה של maximum או minimum של כל ערך מספרי ו-NaN היא NaN.

Multiple mutations and `PropertyMask`

השינויים בנכס מוחלים באופן עקבי אחרי כל שינוי נוסף בבקשה. PropertyMask מגביל את המוטציות insert, update ו-upsert לנכסים שצוינו, אבל לא מגביל את השינויים בנכסים.

לדוגמה, אם מתחילים עם הישות הבאה:

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": 1,
    "b": 2,
    "c": 3
  }
}

הבקשה הבאה מעדכנת את מאפיינים a ו-b, ואז מחילה טרנספורמציה של מאפיין על מאפיין b:

POST https://datastore.googleapis.com/v1/projects/{projectId}:commit
{
  "mode": "NON_TRANSACTIONAL",
  "mutations": [
    {
      "propertyMask": {"a", "b"},  // update property a, b
      "update": {
        "key": {
          "path": [
            {
              "kind": "Kind_1",
              "name": "entity_1"
            }
          ]
        }
        "properties": {
          "a" : "new_value",
          "b" : -2
        }
      },
      "propertyTransforms": [
        {
          "property": "b",
          "increment": { 
            "integerValue": 2
          }
        }
      ]
    }
  ]
}

התוצאה היא:

REST

entity: {
  "key" : {
    "path": [
      {
        "kind": "Kind_1",
        "name": "entity_1"
      }
    ]
  }
  "properties" : {
    "a": "new_value",
    "b": 0,
    "c": 3
  }
}

סוגים ומזהים

כל ישות היא מסוג מסוים, שמסווג את הישות לצורך שאילתות. לדוגמה, באפליקציה של רשימת משימות, כל משימה להשלמה יכולה להיות מיוצגת על ידי ישות מסוג Task.

כל שמות הסוגים שמתחילים בשני קווים תחתונים (__) שמורים ואין להשתמש בהם.

הקצאת מזהים

בנוסף לסוג, לכל ישות יש מזהה שמוקצה לה כשהיא נוצרת. המזהה משויך לישות באופן קבוע ואי אפשר לשנות אותו, כי הוא חלק מהמפתח של הישות. אפשר להקצות אותו באחת משתי דרכים:

האפליקציה יכולה לציין מחרוזת key name משלה עבור הישות.

מידע על הגודל המקסימלי של מחרוזת מפתח הישות מופיע במאמר בנושא מגבלות.
אתם יכולים להגדיר ש-Firestore במצב Datastore יקצה אוטומטית לישות מזהה מספרי שהוא מספר שלם.
בקטע 'מפתחות' במאמר השיטות המומלצות מפורטות שיטות מומלצות להקצאת מזהים.

בדוגמה הבאה נוצר מפתח עם סוג Task שמשתמש בשם המפתח, sampleTask, כמזהה:

C#

Key key = _db.CreateKeyFactory("Task").CreateKey("sampleTask");

Go

taskKey := datastore.NameKey("Task", "sampletask", nil)

Java

Key taskKey = datastore.newKeyFactory().setKind("Task").newKey("sampleTask");

Node.js

const taskKey = datastore.key(['Task', 'sampleTask']);

PHP

$taskKey = $datastore->key('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task", "sampleTask")

Ruby

# task_name = "sampleTask"
task_key = datastore.key "Task", task_name

במצב Datastore, אפשר גם להקצות מזהים באופן אוטומטי. במצב Datastore, המערכת יוצרת רצף אקראי של מזהים לא בשימוש, שמפוזרים באופן אחיד בקירוב. כל מזהה יכול לכלול עד 16 ספרות עשרוניות.

בדוגמה הבאה נוצר מפתח עם סוג Task, בלי להשתמש בשם מפתח. המפתח המלא (כולל המזהה שהוקצה אוטומטית) של הישות יוחזר כששומרים ישות עם מפתח לא שלם במצב Datastore:

C#

Key incompleteKey = _db.CreateKeyFactory("Task").CreateIncompleteKey();
Key key = _db.AllocateId(incompleteKey);

Go

// A complete key is assigned to the entity when it is Put.
taskKey := datastore.IncompleteKey("Task", nil)

Java

KeyFactory keyFactory = datastore.newKeyFactory().setKind("Task");
Key taskKey = datastore.allocateId(keyFactory.newKey());

Node.js

const taskKey = datastore.key('Task');

PHP

$taskKey = $datastore->key('Task');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")

Ruby

task_key = datastore.key "Task"

אם רוצים להציג למשתמש את מזהי הישויות או להסתמך על הסדר שלהן, הכי טוב להשתמש בהקצאה ידנית.

הקצאת מזהה מספרי משלכם

במקום להשתמש במחרוזות של שמות מפתחות או ליצור מזהים מספריים באופן אוטומטי, לפעמים אפליקציות מתקדמות מקצות מזהים מספריים משלהן באופן ידני לישויות שהן יוצרות. עם זאת, חשוב לדעת שאין שום דבר שמונע ממסד נתונים במצב Datastore להקצות לאנטיטי אחר אחד ממזהי המספרים הידניים שלכם. הדרך היחידה להימנע מהתנגשויות כאלה היא להשתמש בשיטה allocateIds() כדי שהאפליקציה תקבל בלוק של מזהים.

מחולל המזהים האוטומטי במצב Datastore עוקב אחרי מזהים שהוקצו באמצעות השיטות האלה, ולא ישתמש בהם שוב עבור ישות אחרת. כך אפשר להשתמש במזהים כאלה בבטחה בלי שיהיו התנגשויות. אי אפשר לבחור באופן ידני אילו ערכים יוחזרו על ידי ה-method‏ allocateIds(). הערכים שמוחזרים על ידי allocateIds() מוקצים על ידי מצב Datastore.

נתיבי צאצאים

הישויות במסד נתונים במצב Datastore יוצרות מרחב במבנה היררכי, בדומה למבנה הספריות של מערכת קבצים. כשיוצרים ישות, אפשר להגדיר ישות אחרת כהורה שלה. הישות החדשה היא צאצא של ישות ההורה (שימו לב: בניגוד למערכת קבצים, ישות ההורה לא חייבת להתקיים בפועל). ישות ללא הורה היא ישות בסיסית. השיוך בין ישות לבין ההורה שלה הוא קבוע, ואי אפשר לשנות אותו אחרי שהישות נוצרת. במצב Datastore לעולם לא יוקצה אותו מזהה מספרי לשתי ישויות עם אותו הורה, או לשתי ישויות בסיס (ישויות ללא הורה).

לישות יכולות להיות כמה רמות של ישויות אב וישויות צאצא. ההורה של ישות, ההורה של ההורה וכן הלאה באופן רקורסיבי הם האבות הקדמונים שלה. הילדים שלה, הילדים של הילדים וכן הלאה הם הצאצאים שלה. הרצף של ישויות שמתחילות בישות בסיסית וממשיכות מהורה לצאצא, עד לישות נתונה, מהווה את נתיב האב של הישות הזו. המפתח המלא שמזהה את הישות מורכב מרצף של זוגות סיווג-מזהה שמציינים את נתיב ישות האב שלה ומסתיימים בזוגות של הישות עצמה:

[User:alice, TaskList:default, Task:sampleTask]

עבור ישות שורש, נתיב ישות האב ריק והמפתח מורכב רק מסיווג הישות ומזהה הישות:

[User:alice]

רמות של הורים

אפשר להשתמש ברמות של הורים כדי לארגן את הנתונים. לדוגמה, אם האפליקציה שלכם מארגנת Task ישויות לפי TaskList ישויות, צריך להשתמש ברמה אחת של הורה:

C#

Key rootKey = _db.CreateKeyFactory("TaskList").CreateKey("default");
Key key = new KeyFactory(rootKey, "Task").CreateKey("sampleTask");

Go

parentKey := datastore.NameKey("TaskList", "default", nil)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

Key taskKey =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("TaskList", "default"))
        .setKind("Task")
        .newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("TaskList", "default", "Task", "sampleTask")
# Alternatively
parent_key = client.key("TaskList", "default")
key = client.key("Task", "sampleTask", parent=parent_key)

Ruby

# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key [["TaskList", task_list_name], ["Task", task_name]]

אם האפליקציה שלכם מארגנת Task ישויות קודם לפי User ישויות ואז לפי TaskList ישויות, צריך להשתמש בכמה רמות של ישויות אב:

C#

Key rootKey = _db.CreateKeyFactory("User").CreateKey("Alice");
Key taskListKey = new KeyFactory(rootKey, "TaskList").CreateKey("default");
Key key = new KeyFactory(taskListKey, "Task").CreateKey("sampleTask");

Go

userKey := datastore.NameKey("User", "alice", nil)
parentKey := datastore.NameKey("TaskList", "default", userKey)
taskKey := datastore.NameKey("Task", "sampleTask", parentKey)

Java

KeyFactory keyFactory =
    datastore
        .newKeyFactory()
        .addAncestors(PathElement.of("User", "Alice"), PathElement.of("TaskList", "default"))
        .setKind("Task");
Key taskKey = keyFactory.newKey("sampleTask");

Node.js

const taskKey = datastore.key([
  'User',
  'alice',
  'TaskList',
  'default',
  'Task',
  'sampleTask',
]);

PHP

$taskKey = $datastore->key('User', 'alice')
    ->pathElement('TaskList', 'default')
    ->pathElement('Task', 'sampleTask');

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("User", "alice", "TaskList", "default", "Task", "sampleTask")

Ruby

# user_name = "alice"
# task_list_name = "default"
# task_name = "sampleTask"
task_key = datastore.key([
                           ["User", user_name],
                           ["TaskList", task_list_name],
                           ["Task", task_name]
                         ])

כפי שמוצג בדוגמה הקודמת, כשיוצרים ישות עם הורה, מציינים את הנתיב המלא של ההורה.

יכול להיות שאפליקציה ששומרת פרופילים של משתמשים תדרוש רק רמה אחת של הורה לנתוני הפרופיל של המשתמש. לדוגמה, אפשר להשתמש בנתיב אב יחיד User עבור ישויות Profile:

[User:alice, Profile:public]

אפליקציה שמאפשרת לתזמן שימוש בחדרי ישיבות עשויה לדרוש כמה רמות של הורים, כמו נתיב אב קדמון Building/Floor ברמות שונות עבור ישויות Room:

[Building:C, Floor:1, Room:123]

קבוצות ישויות

קבוצת ישויות מורכבת מישות בסיסית וכל הישויות שנגזרות ממנה. בדרך כלל, אפליקציות משתמשות בקבוצות של ישויות כדי לארגן נתונים שקשורים זה לזה. לדוגמה, אפליקציה יכולה להשתמש בקבוצת ישויות כדי לאחסן נתונים על מוצר אחד או על פרופיל משתמש אחד.

מאפיינים וסוגי ערכים

ערכי הנתונים שמשויכים לישות מורכבים ממאפיין אחד או יותר. לכל מאפיין יש שם וערך אחד או יותר.

למאפיין יכולים להיות ערכים מכמה סוגים, ולשתי ישויות יכולים להיות ערכים מסוגים שונים לאותו מאפיין. אפשר להוסיף מאפיין לאינדקס או להסיר אותו מהאינדקס (שאילתות שממיינות או מסננות לפי מאפיין p יתעלמו מישויות שבהן p לא מופיע באינדקס).

דוגמאות לנכסים:

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["category"] = "Personal",
    ["created"] = new DateTime(1999, 01, 01, 0, 0, 0, DateTimeKind.Utc),
    ["done"] = false,
    ["priority"] = 4,
    ["percent_complete"] = 10.0,
    ["description"] = new Value()
    {
        StringValue = "Learn Cloud Datastore",
        ExcludeFromIndexes = true
    },
};

Go

type Task struct {
	Category        string
	Done            bool
	Priority        int
	Description     string `datastore:",noindex"`
	PercentComplete float64
	Created         time.Time
}
task := &Task{
	Category:        "Personal",
	Done:            false,
	Priority:        4,
	Description:     "Learn Cloud Datastore",
	PercentComplete: 10.0,
	Created:         time.Now(),
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("category", "Personal")
        .set("created", Timestamp.now())
        .set("done", false)
        .set("priority", 4)
        .set("percent_complete", 10.0)
        .set(
            "description",
            StringValue.newBuilder("Learn Cloud Datastore").setExcludeFromIndexes(true).build())
        .build();

Node.js

const task = [
  {
    name: 'category',
    value: 'Personal',
  },
  {
    name: 'created',
    value: new Date(),
  },
  {
    name: 'done',
    value: false,
  },
  {
    name: 'priority',
    value: 4,
  },
  {
    name: 'percent_complete',
    value: 10.0,
  },
  {
    name: 'description',
    value: 'Learn Cloud Datastore',
    excludeFromIndexes: true,
  },
];

PHP

$task = $datastore->entity(
    $key,
    [
        'category' => 'Personal',
        'created' => new DateTime(),
        'done' => false,
        'priority' => 4,
        'percent_complete' => 10.0,
        'description' => 'Learn Cloud Datastore'
    ],
    ['excludeFromIndexes' => ['description']]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

import datetime

key = client.key("Task")
task = datastore.Entity(key, exclude_from_indexes=("description",))
task.update(
    {
        "category": "Personal",
        "description": "Learn Cloud Datastore",
        "created": datetime.datetime.now(tz=datetime.timezone.utc),
        "done": False,
        "priority": 4,
        "percent_complete": 10.5,
    }
)
client.put(task)

Ruby

task = datastore.entity "Task" do |t|
  t["category"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
  t.exclude_from_indexes! "description", true
end

מאפייני מערך

מאפיין עם יותר מערך אחד נקרא מאפיין מערך. בדוגמה הזו יש שני מאפייני מערך. הראשון נקרא tags והערכים שלו הם fun ו-programming. השני נקרא collaborators והערכים שלו הם alice ו-bob.

C#

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

מאפייני מערך יכולים להיות שימושיים, למשל, כשמבצעים שאילתות עם מסנני שוויון: ישות עומדת בדרישות השאילתה אם אחד מהערכים שלה במאפיין תואם לערך שצוין במסנן. מידע נוסף על מאפייני מערך, כולל בעיות שכדאי להיות מודעים אליהן, מופיע בנושא שאילתות.

סוגי ערכים נתמכים

המאפיינים מאוחסנים כמפה string/value שמכילה את שמות המאפיינים והערכים של הישות. הסוגים הבאים נתמכים לערכים:

מערך

‫API בארכיטקטורת REST
- שם השדה: arrayValue
- ‫type: אובייקט ArrayValue שמכיל מערך של אובייקטים של ערכי JSON
- אפשר להקצות מאפיין מסוג מערך באמצעות השדה arrayValue, שהוא מסוג ArrayValue, ולהגדיר את השדה values שלו למערך של ערכים. כדי להגדיר נכס כלא מאונדקס, צריך להגדיר את השדה excludeFromIndexes של אובייקט הערך של הנכס כ-true.
API ל-RPC
- שם השדה: array_value
- סוג: ArrayValue הודעה שמכילה הודעה אחת או יותר Value
- אפשר להקצות מאפיין מסוג מערך באמצעות השדה array_value, שהוא מסוג ArrayValue, ולאכלס את השדה values שלו בכמה אובייקטים מסוג Value. כדי להסיר נכס מהאינדקס, מגדירים את השדה exclude_from_indexes של Value לערך true.
סדר המיון: ללא
הערות: אי אפשר להשתמש בערך מערך אחר. במופע של הערך אסור להגדיר את meaning או את exclude_from_indexes.

בוליאני

‫API בארכיטקטורת REST
- שם השדה: booleanValue
- type: true or false
RPC API
- שם השדה: boolean_value
- סוג: bool
סדר המיון: false<true

Blob

‫API בארכיטקטורת REST
- שם השדה: blobValue
- סוג: מחרוזת. הקידוד חייב להיות לפי base64.
RPC API
- שם השדה: blob_value
- סוג: bytes
סדר המיון: סדר הבייטים
הערות: עד 1,500 בייט אם הנכס מאונדקס, עד 1,048,487 בייט (1MiB – 89 בייט) אחרת.

תאריך ושעה

‫API בארכיטקטורת REST
- שם השדה: timestampValue
- סוג: מחרוזת (בפורמט RFC 3339, עם אלפיות השנייה, לדוגמה 2013-05-14T00:01:00.234Z)
RPC API
- שם השדה: timestamp_value
- סוג: Timestamp
סדר המיון: כרונולוגי
הערות:
- כשמאחסנים נתונים במצב Datastore, הדיוק הוא עד מיקרו-שניות בלבד. כל דיוק נוסף מעוגל כלפי מטה.
- כשמחזירים את הערך הזה כחלק משאילתת הקרנה, במצב Datastore מומרים ערכי חותמת הזמן לערכים של מספרים שלמים במיקרו-שנייה.

ישות מוטמעת

‫API בארכיטקטורת REST
- שם השדה: entityValue
- ‫type: ישות JSON
RPC API
- שם השדה: entity_value
- סוג: הודעה אחת (Entity)
סדר המיון: ללא
הערות: כשמבצעים אינדוקס, אפשר לשלוח שאילתות לגבי מאפייני משנה. אם מחריגים את הערך הזה מהוספה לאינדקס, כל נכסי המשנה מוחרגים גם הם מהוספה לאינדקס.

מספר בשיטת נקודה צפה

‫API בארכיטקטורת REST
- שם השדה: doubleValue
- type: number
RPC API
- שם השדה: double_value
- סוג: double
סדר המיון: מספרי
הערות: דיוק כפול של 64 ביט, IEEE 754

נקודה גיאוגרפית

‫API בארכיטקטורת REST
- שם השדה: geoPointValue
- ‫type: זוג של קו רוחב וקו אורך ב-JSON
RPC API
- שם השדה: geo_point_value
- הקלדה: הודעת LatLng
סדר המיון: לפי קו רוחב, ואז לפי קו אורך

מספר שלם

‫API בארכיטקטורת REST
- שם השדה: integerValue
- סוג: מספר או מחרוזת. משתמשים במחרוזות למספרים שלמים שלא ניתן לייצג בדיוק כמספרים.
RPC API
- שם השדה: integer_value
- סוג: int64
סדר המיון: מספרי

מפתח

‫API בארכיטקטורת REST
- שם השדה: keyValue
- ‫type: מפתח במצב Datastore ב-JSON
RPC API
- שם השדה: key_value
- הקלדה: הודעת Key
סדר המיון: לפי רכיבי הנתיב (סוג, מזהה, סוג, מזהה...)

Null

‫API בארכיטקטורת REST
- שם השדה: nullValue
- type: null
RPC API
- שם השדה: null_value
- סוג: NullValue
סדר המיון: ללא

מחרוזת טקסט

‫API בארכיטקטורת REST
- שם השדה: stringValue
- type: string
RPC API
- שם השדה: string_value
- סוג: string
סדר המיון: סדר הבייטים בקידוד UTF-8
הערות: עד 1,500 בייט אם הנכס מאונדקס, עד 1,048,487 בייט (1MiB – 89 בייט) אחרת.

סדר של סוגי ערכים

כששאילתה כוללת נכס עם ערכים מסוגים מעורבים, מסד נתונים במצב Datastore משתמש בסדר דטרמיניסטי שמבוסס על הייצוגים הפנימיים. הרשימה הבאה מציגה את הסדר:

ערכי Null
מספרים עם נקודה קבועה
- מספרים שלמים
- תאריכים ושעות
ערכים בוליאניים
מחרוזות בייטים
מחרוזות Unicode
מספרים בשיטת נקודה צפה
ערכי NaN
נקודות גיאוגרפיות
מפתחות במצב Datastore

ישויות, מאפיינים ומפתחות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

עבודה עם ישויות

יצירת ישות

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

אחזור ישות

C#

Go

Java

Node.js

PHP

Python

Ruby

עדכון ישות

C#

Go

Java

Node.js

PHP

Python

Ruby

מחיקת ישות

C#

Go

Java

Node.js

PHP

Python

Ruby

פעולות באצווה

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

C#

Go

Java

Node.js

PHP

Python

Ruby

הגדלה של ערך מאפיין ושינויים אחרים במאפיינים

REST

REST

REST

סוגים מעורבים עם maximum ועם minimum

Multiple mutations and PropertyMask

REST

REST

סוגים ומזהים

הקצאת מזהים

ישויות, מאפיינים ומפתחות

סוגים מעורבים עם `maximum` ועם `minimum`

Multiple mutations and `PropertyMask`