نموذج بيانات Cloud Firestore

Cloud Firestore هي قاعدة بيانات مستندية مستندة إلى NoSQL. وعلى عكس قاعدة بيانات SQL، لا تتضمّن أيّ جداول أو صفوف. بدلاً من ذلك، يمكنك تخزين البيانات في مستندات يتم تنظيمها في مجموعات.

يحتوي كل مستند على مجموعة من أزواج المفاتيح والقيم. Cloud Firestore هو مُحسَّن لتخزين مجموعات كبيرة من المستندات الصغيرة.

يجب تخزين جميع المستندات في مجموعات. يمكن أن تحتوي المستندات على مجموعات فرعية وعناصر متداخلة، ويمكن أن تتضمّن كلتا المجموعتَين حقولًا أساسية مثل السلاسل أو عناصر معقدة مثل القوائم.

يتم إنشاء المجموعات والمستندات بشكل ضمني في Cloud Firestore. ما عليك سوى إسناد البيانات إلى مستند ضمن مجموعة. إذا لم تكن المجموعة أو المستند متوفّرَين، تنشئ Cloud Firestore المجموعة أو المستند.

المستندات

في Cloud Firestore، تكون وحدة التخزين هي المستند. المستند هو سجلّ خفيف يحتوي على حقول ترتبط بالقيم. يتم تحديد كل مستند باسم.

قد يبدو المستند الذي يمثّل مستخدمًا alovelace على النحو التالي:

• alovelace

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

ملاحظة: يتيح Cloud Firestore مجموعة متنوعة من أنواع البيانات للقيم: قيمة منطقية ورقم وسلسلة ونقطة جغرافية وكتلة ثنائية كبيرة وطابع زمني. يمكنك أيضًا استخدام المصفوفات أو العناصر المُدمجة، والتي تُعرف باسم الخرائط، لتنظيم البيانات ضمن مستند.

تُعرف الكائنات المعقدة والمُدمجة في المستند باسم الخرائط. على سبيل المثال، يمكنك تنظيم اسم المستخدم من المثال أعلاه باستخدام خريطة، على النحو التالي:

• alovelace

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

قد تلاحظ أنّ المستندات تشبه إلى حد كبير ملفات JSON. في الواقع، هذا هو الحال. هناك بعض الاختلافات (على سبيل المثال، تتيح المستندات أنواع بيانات إضافية و يكون حجمها محدودًا بـ 1 ميغابايت)، ولكن بشكل عام، يمكنك التعامل مع المستندات على أنّها سجلّات JSON خفيفة الوزن.

المجموعات

يتم تخزين المستندات في مجموعات، وهي ببساطة حاويات للمستندات. على سبيل المثال، يمكن أن تتضمّن مجموعة users المستخدمين المختلفين، وكل واحد منهم يمثّل مستندًا:

• مستخدم

  • alovelace

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

  • aturing

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

Cloud Firestore لا يتضمّن مخطّطًا، لذا لديك حرية كاملة في تحديد الحقول التي تضعها في كل مستند وأنواع البيانات التي تخزّنها في هذه الحقول. يمكن أن تحتوي جميع المستندات ضمن المجموعة نفسها على حقول مختلفة أو تخزِّن أنواعًا مختلفة من البيانات في هذه الحقول. ومع ذلك، من المستحسن استخدام الحقول وأنواع البيانات نفسها في عدة مستندات، حتى تتمكّن من إجراء استعلامات عن المستندات بسهولة أكبر.

تحتوي المجموعة على مستندات فقط. ولا يمكن أن تحتوي مباشرةً على ملف شخصي أساسي يحتوي على قيم، ولا يمكن أن تحتوي على مجموعات أخرى. (اطّلِع على البيانات الهيكلية للحصول على شرح حول كيفية تنظيم data أكثر تعقيدًا في Cloud Firestore.)

تكون أسماء المستندات ضمن مجموعة فريدة. يمكنك تقديم مفاتيح خاصة بك، مثل أرقام تعريف المستخدمين، أو يمكنك السماح لـ Cloud Firestore بإنشاء أرقام تعريف عشوائية نيابةً عنك تلقائيًا.

لست بحاجة إلى "إنشاء" مجموعات أو "حذفها". بعد إنشاء الوثيقة الأولى في مجموعة، تصبح المجموعة متوفّرة. إذا حذفت كل الاطّلاع على المحتوى في الروابط. المستندات في مجموعة، لن تعود متوفّرة.

المراجع

يتم تعريف كل مستند في Cloud Firestore بشكل فريد من خلال موقعه داخل قاعدة البيانات. عرض المثال السابق المستند alovelace ضمن المجموعة users. للإشارة إلى هذا الموقع في الرمز، يمكنك إنشاء إشارة إليه.

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { doc } from "firebase/firestore";

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات App Clip.

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

جافا

// 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

انتقال

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 المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { collection } from "firebase/firestore";

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات App Clip.

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

جافا

// 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

انتقال

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

ملاحظة: مراجع المجموعات ومراجع المستندات نوعان مختلفان من المراجع، ويتيحان لك تنفيذ عمليات مختلفة. على سبيل المثال، يمكنك استخدام مرجع مجموعة لطلب البحث عن المستندات في المجموعة، ويمكنك استخدام مرجع مستند لقراءة مستند فردي أو كتابته.

للتيسير، يمكنك أيضًا إنشاء مراجع من خلال تحديد مسار مستند أو مجموعة كسلسلة، مع فصل مكوّنات المسار بشرطة مائلة للأمام (/). على سبيل المثال، لإنشاء مرجع إلى مستند alovelace:

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { doc } from "firebase/firestore"; 

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات App Clip.

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

جافا

// 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

انتقال

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 لتخزين غرف المحادثات المختلفة:

• غرفة

  • غرفة أ

    name : "my chat room"
    

  • غرفة ب

    ...
    

بعد أن أصبحت لديك غرف محادثة، حدِّد طريقة تخزين رسائلك. قد لا تريد تخزينها في مستند غرفة المحادثة. يجب أن تكون المستندات في Cloud Firestore خفيفة الوزن، ويمكن أن تحتوي غرفة المحادثة على عدد كبير من الرسائل. ومع ذلك، يمكنك إنشاء مجموعات إضافية في مستند غرفة المحادثة، كمجموعات فرعية.

المجموعات الفرعية

إنّ أفضل طريقة لتخزين الرسائل في هذا السيناريو هي استخدام المجموعات الفرعية. تشكل المجموعة الفرعية مجموعة مرتبطة بمستند معيّن.

ملاحظة: يمكنك البحث في جميع المجموعات الفرعية التي تحمل معرّف المجموعة نفسه باستخدام طلبات بحث مجموعات المجموعات.

يمكنك إنشاء مجموعة فرعية باسم messages لكل مستند غرفة في مجموعة rooms:

• غرفة

  • غرفة أ

    name : "my chat room"
    

    • الرسائل

      • message1

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

      • message2

        ...
        

  • غرفة ب

    ...
    

في هذا المثال، يمكنك إنشاء إشارة إلى رسالة في المجموعة الفرعية باستخدام الرمز البرمجي التالي:

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { doc } from "firebase/firestore"; 

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات App Clip.

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

جافا

// 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

انتقال

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 لم يعُد متوفّرًا. إذا كنت تريد حذف المستندات في المجموعات الفرعية عند حذف مستند رئيسي، عليك إجراء ذلك يدويًا، كما هو موضّح في حذف المجموعات.