מודל נתונים של Cloud Firestore

Cloud Firestore הוא מסד נתונים מסוג NoSQL שמתמקד במסמכים. בניגוד למסד נתונים של SQL, אין טבלאות או שורות. במקום זאת, הנתונים מאוחסנים במסמכים, שמאורגנים באוספים.

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

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

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

מסמכים

ב-Cloud Firestore, יחידת האחסון היא המסמך. מסמך הוא רשומה קטנה מדי שמכילה שדות, שממופים לערכים. לכל מסמך יש שם.

מסמך שמייצג משתמש alovelace עשוי להיראות כך:

• alovelace

  first : "Ada"
last : "Lovelace"
born : 1815
  

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

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

• שרוך זוהר בצבע

  name :
    first : "Ada"
    last : "Lovelace"
born : 1815
  

יכול להיות שתבחינו שהמסמכים דומים מאוד ל-JSON. למעשה, הם בעצם כאלה. יש כמה הבדלים (למשל, מסמכים תומכים בסוגי נתונים נוספים והגודל שלהם מוגבל ל-1MB), אבל באופן כללי אפשר להתייחס למסמכים כרשומות JSON קלות.

אוספים

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

• משתמשים

  • alovelace

    first : "Ada"
last : "Lovelace"
born : 1815
    

  • בנסיעה

    first : "Alan"
last : "Turing"
born : 1912
    

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

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

שמות המסמכים בתוך אוסף הם ייחודיים. אתם יכולים לספק מפתחות משלכם, כמו מזהי משתמשים, או לאפשר ל-Cloud Firestore ליצור בשבילכם מזהים רנדומליים באופן אוטומטי.

אין צורך 'ליצור' או 'למחוק' אוספים. אחרי שיוצרים את המסמך הראשון באוסף, האוסף קיים. אם מוחקים את כל המסמכים באוסף, הוא לא קיים יותר.

קובצי עזר

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

Web

מידע נוסף על ממשק ה-API המודולרי האינטרנטי שניתן לנער אותו ולשדרג מה-API עם מרחב השמות.

import { doc } from "firebase/firestore";

const alovelaceDocumentRef = doc(db, 'users', 'alovelace');
doc_reference.js

Web

מידע נוסף על ממשק ה-API המודולרי האינטרנטי שניתן לנער אותו ולשדרג מה-API עם מרחב השמות.

var alovelaceDocumentRef = db.collection('users').doc('alovelace');
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

let alovelaceDocumentRef = db.collection("users").document("alovelace")
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ביעדים מסוגwatchOS ו-קליפ של אפליקציה.

FIRDocumentReference *alovelaceDocumentRef =
    [[self.db collectionWithPath:@"users"] documentWithPath:@"alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.collection("users").document("alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.collection("users").document("alovelace");
DocSnippets.java

Dart

final alovelaceDocumentRef = db.collection("users").doc("alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.collection("users").document("alovelace");
References.java

Python

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

Python

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

C++‎

DocumentReference alovelace_document_reference =
    db->Collection("users").Document("alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.collection('users').doc('alovelace');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createDocReference(client *firestore.Client) {

	alovelaceRef := client.Collection("users").Doc("alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document.go

PHP

PHP

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

$document = $db->collection('samples/php/users')->document('alovelace');
data_reference_document.php

Unity

DocumentReference documentRef = db.Collection("users").Document("alovelace");

C#‎

C#‎

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

DocumentReference documentRef = db.Collection("users").Document("alovelace");
Program.cs

Ruby

document_ref = firestore.col("users").doc("alovelace")
data_model.rb

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

אפשר גם ליצור הפניות לאוספים:

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

import { collection } from "firebase/firestore";

const usersCollectionRef = collection(db, 'users');
collection_reference.js

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

var usersCollectionRef = db.collection('users');
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

let usersCollectionRef = db.collection("users")
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ביעדים מסוגwatchOS ו-קליפ של אפליקציה.

FIRCollectionReference *usersCollectionRef = [self.db collectionWithPath:@"users"];
ViewController.m

Kotlin+KTX

val usersCollectionRef = db.collection("users")
DocSnippets.kt

Java

CollectionReference usersCollectionRef = db.collection("users");
DocSnippets.java

Dart

final usersCollectionRef = db.collection("users");
firestore.dart

Java

// Reference to the collection "users"
CollectionReference collection = db.collection("users");
References.java

Python

users_ref = db.collection("users")
snippets.py

Python

users_ref = db.collection("users")
snippets.py

C++‎

CollectionReference users_collection_reference = db->Collection("users");
snippets.cpp

Node.js

const usersCollectionRef = db.collection('users');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createCollectionReference(client *firestore.Client) {
	usersRef := client.Collection("users")

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

PHP

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

$collection = $db->collection('samples/php/users');
data_reference_collection.php

Unity

CollectionReference collectionRef = db.Collection("users");

C#‎

C#‎

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

CollectionReference collectionRef = db.Collection("users");
Program.cs

Ruby

collection_ref = firestore.col "users"
data_model.rb

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

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

import { doc } from "firebase/firestore"; 

const alovelaceDocumentRef = doc(db, 'users/alovelace');
doc_reference_alternative.js

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

var alovelaceDocumentRef = db.doc('users/alovelace');
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

let aLovelaceDocumentReference = db.document("users/alovelace")
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ביעדים מסוגwatchOS ו-קליפ של אפליקציה.

FIRDocumentReference *aLovelaceDocumentReference =
    [self.db documentWithPath:@"users/alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.document("users/alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.document("users/alovelace");
DocSnippets.java

Dart

final aLovelaceDocRef = db.doc("users/alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.document("users/alovelace");
References.java

Python

a_lovelace_ref = db.document("users/alovelace")
snippets.py

Python

a_lovelace_ref = db.document("users/alovelace")
snippets.py

C++‎

DocumentReference alovelace_document = db->Document("users/alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.doc('users/alovelace');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createDocReferenceFromString(client *firestore.Client) {
	// Reference to a document with id "alovelace" in the collection "users"
	alovelaceRef := client.Doc("users/alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document_path.go

PHP

PHP

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

$document = $db->document('users/alovelace');
data_reference_document_path.php

Unity

DocumentReference documentRef = db.Document("users/alovelace");

C#‎

C#‎

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

DocumentReference documentRef = db.Document("users/alovelace");
Program.cs

Ruby

document_path_ref = firestore.doc "users/alovelace"
data_model.rb

נתונים היררכיים

כדי להבין איך מבנים היררכיים של נתונים פועלים ב-Cloud Firestore, נבחן דוגמה לאפליקציית צ'אט עם הודעות וחדרי צ'אט.

אפשר ליצור אוסף בשם rooms כדי לאחסן חדרי צ'אט שונים:

• חדרים

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

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

אוספי משנה

הדרך הטובה ביותר לאחסן הודעות בתרחיש הזה היא באמצעות אוספי משנה. אוסף משנה הוא אוסף שמשויך למסמך ספציפי.

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

אפשר ליצור אוסף משנה בשם messages לכל מסמך של חדר באוסף rooms:

• חדרים

  • חדר אחד ()

    name : "my chat room"
    

    • הודעות

      • message1

        from : "alex"
msg : "Hello World!"
        

      • הודעה2

        ...
        

  • roomB

    ...
    

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

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

import { doc } from "firebase/firestore"; 

const messageRef = doc(db, "rooms", "roomA", "messages", "message1");
subcollection_reference.js

Web

מידע נוסף על Web API מודולרי שניתן לניפוי עצים ושדרוג מ-API עם מרחבי שמות.

var messageRef = db.collection('rooms').doc('roomA')
                .collection('messages').doc('message1');
test.firestore.js

Swift

הערה: המוצר הזה לא זמין ליעדים של watchOS ו-App Clip.

let messageRef = db
  .collection("rooms").document("roomA")
  .collection("messages").document("message1")
ViewController.swift

Objective-C

הערה: המוצר הזה לא זמין ביעדים מסוגwatchOS ו-קליפ של אפליקציה.

FIRDocumentReference *messageRef =
    [[[[self.db collectionWithPath:@"rooms"] documentWithPath:@"roomA"]
    collectionWithPath:@"messages"] documentWithPath:@"message1"];
ViewController.m

Kotlin+KTX

val messageRef = db
    .collection("rooms").document("roomA")
    .collection("messages").document("message1")
DocSnippets.kt

Java

DocumentReference messageRef = db
        .collection("rooms").document("roomA")
        .collection("messages").document("message1");
DocSnippets.java

Dart

final messageRef = db
    .collection("rooms")
    .doc("roomA")
    .collection("messages")
    .doc("message1");
firestore.dart

Java

// Reference to a document in subcollection "messages"
DocumentReference document =
    db.collection("rooms").document("roomA").collection("messages").document("message1");
References.java

Python

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

Python

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

C++‎

DocumentReference message_reference = db->Collection("rooms")
    .Document("roomA")
    .Collection("messages")
    .Document("message1");
snippets.cpp

Node.js

const messageRef = db.collection('rooms').doc('roomA')
  .collection('messages').doc('message1');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createSubcollectionReference(client *firestore.Client) {
	messageRef := client.Collection("rooms").Doc("roomA").
		Collection("messages").Doc("message1")

	_ = messageRef
}
retrieve_data_reference_subcollection.go

PHP

PHP

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

$document = $db
    ->collection('rooms')
    ->document('roomA')
    ->collection('messages')
    ->document('message1');
data_reference_subcollection.php

Unity

DocumentReference documentRef = db
	.Collection("Rooms").Document("RoomA")
	.Collection("Messages").Document("Message1");

C#‎

C#‎

מידע נוסף על התקנה ויצירה של לקוח Cloud Firestore זמין במאמר ספריות לקוח של Cloud Firestore.

DocumentReference documentRef = db
    .Collection("Rooms").Document("RoomA")
    .Collection("Messages").Document("Message1");
Program.cs

Ruby

message_ref = firestore.col("rooms").doc("roomA").col("messages").doc("message1")
data_model.rb

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

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

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

אזהרה: מחיקת מסמך לא מוחקת את האוספים המשניים שלו.

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