Quickstart

This quickstart shows you how to set up Cloud Firestore, add data, and read data by using the C#, Go, Java, Node.js, PHP, Python, or Ruby server client library.

Before you begin

Sign in to your Google Account.
If you don't already have one, sign up for a new account.
Select or create a GCP project.

Go to the Manage resources page

Create a Cloud Firestore in Native mode database

If this is a new project, you will need to create a Cloud Firestore database instance.

Go to the Cloud Firestore viewer
From the Select a database service screen, choose Cloud Firestore in Native mode.
Select a Cloud Firestore location. Click Create Database.

When you create a Cloud Firestore project, it also enables the API in the Cloud API Manager.

Set up authentication

To run the client library, you must first set up authentication by creating a service account and setting an environment variable.

GCP Console

Go to the Create service account key page in the GCP Console.
Go to the Create Service Account Key page
From the Service account drop-down list, select New service account.
Enter a name into the Service account name field.
From the Role drop-down list, select Project > Owner.

Note: The Role field authorizes your service account to access resources. You can view and change this field later using GCP Console. If you are developing a production application, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts.
Click Create. A JSON file that contains your key downloads to your computer.

Command line

You can run the following commands using the Cloud SDK on your local machine, or within Cloud Shell.

Create the service account. Replace [NAME] with your desired service account name.
```
gcloud iam service-accounts create [NAME]
```
Grant permissions to the service account. Replace [PROJECT_ID] with your project ID.
```
gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
```
Note: The Role field authorizes your service account to access resources. You can view and change this field later using GCP Console. If you are developing a production application, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts.

Generate the key file. Replace [FILE_NAME] with a name for the key file.

gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. Replace [PATH] with the file path of the JSON file that contains your service account key, and [FILE_NAME] with the filename. This variable only applies to your current shell session, so if you open a new session, set the variable again.

Linux or macOS

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/[FILE_NAME].json"

Windows

With PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"

With command prompt:

set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

Add the server client library to your app

Add the required dependencies and client libraries to your app.

Java

Add the Cloud Firestore Java library to your app:

Using Gradle:

compile 'com.google.cloud:google-cloud-firestore:0.58.0-beta'

Using Maven:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-firestore</artifactId>
  <version>0.60.0-beta</version>
</dependency>pom.xml

Python

Add the Cloud Firestore Python library to your app:

Note: We recommend that you use a virtual Python environment to install the Cloud Firestore Python library:

pip install virtualenv
virtualenv env
source env/bin/activate

pip install --upgrade google-cloud-firestore

Node.js

Add the Cloud Firestore Node.js library to your app:

npm install --save @google-cloud/firestore

Go

Install the Cloud Firestore Go library:

go get "cloud.google.com/go"

Add the Cloud Firestore Go library to your app:

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

PHP

Install and enable the gRPC extension for PHP, which you will need to use the client library.
Add the Cloud Firestore PHP library to your app:
```
composer require google/cloud-firestore
```

C#

Add the Cloud Firestore C# library to your app in your .csproj file:

<ItemGroup>
  <PackageReference Include="Google.Cloud.Firestore" Version="1.0.0-beta06" />
</ItemGroup>

Add the following to your Program.cs file:
```
using Google.Cloud.Firestore;
```

Ruby

Add the Cloud Firestore Ruby library to your app in your Gemfile:
```
gem "google-cloud-firestore"
```
Install dependencies from your Gemfile using:
```
bundle install
```

Initialize Cloud Firestore

Initialize an instance of Cloud Firestore:

Java

import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;
FirestoreOptions firestoreOptions =
    FirestoreOptions.getDefaultInstance().toBuilder()
        .setProjectId(projectId)
        .build();
Firestore db = firestoreOptions.getService();Quickstart.java

Python

from google.cloud import firestore

# Project ID is determined by the GCLOUD_PROJECT environment variable
db = firestore.Client()snippets.py

Node.js

const Firestore = require('@google-cloud/firestore');

const db = new Firestore({
  projectId: 'YOUR_PROJECT_ID',
  keyFilename: '/path/to/keyfile.json',
});

Go

// Sets your Google Cloud Platform project ID.
projectID := "YOUR_PROJECT_ID"

// Get a Firestore client.
client, err := firestore.NewClient(ctx, projectID)
if err != nil {
	log.Fatalf("Failed to create client: %v", err)
}

// Close client when done.
defer client.Close()main.go

PHP

use Google\Cloud\Firestore\FirestoreClient;

/**
 * Initialize Cloud Firestore with default project ID.
 * ```
 * initialize();
 * ```
 */
function initialize()
{
    // Create the Cloud Firestore client
    $db = new FirestoreClient();
    printf('Created Cloud Firestore client with default project ID.' . PHP_EOL);
}initialize.php

C#

FirestoreDb db = FirestoreDb.Create(project);
Console.WriteLine("Created Cloud Firestore client with project ID: {0}", project);Program.cs

Ruby

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new project_id: project_id

puts "Created Cloud Firestore client with given project ID."quickstart.rb

Add data

Cloud Firestore stores data in Documents, which are stored in Collections. Cloud Firestore creates collections and documents implicitly the first time you add data to the document. You do not need to explicitly create collections or documents.

Create a new collection and a document using the following example code.

Java

DocumentReference docRef = db.collection("users").document("alovelace");
// Add document data  with id "alovelace" using a hashmap
Map<String, Object> data = new HashMap<>();
data.put("first", "Ada");
data.put("last", "Lovelace");
data.put("born", 1815);
//asynchronously write data
ApiFuture<WriteResult> result = docRef.set(data);
// ...
// result.get() blocks on response
System.out.println("Update time : " + result.get().getUpdateTime());Quickstart.java

Python

doc_ref = db.collection(u'users').document(u'alovelace')
doc_ref.set({
    u'first': u'Ada',
    u'last': u'Lovelace',
    u'born': 1815
})snippets.py

Node.js

var docRef = db.collection('users').doc('alovelace');

var setAda = docRef.set({
  first: 'Ada',
  last: 'Lovelace',
  born: 1815
});index.js

Go

_, _, err = client.Collection("users").Add(ctx, map[string]interface{}{
	"first": "Ada",
	"last":  "Lovelace",
	"born":  1815,
})
if err != nil {
	log.Fatalf("Failed adding alovelace: %v", err)
}main.go

PHP

$docRef = $db->collection('users')->document('lovelace');
$docRef->set([
    'first' => 'Ada',
    'last' => 'Lovelace',
    'born' => 1815
]);
printf('Added data to the lovelace document in the users collection.' . PHP_EOL);add_data.php

C#

DocumentReference docRef = db.Collection("users").Document("alovelace");
Dictionary<string, object> user = new Dictionary<string, object>
{
    { "First", "Ada" },
    { "Last", "Lovelace" },
    { "Born", 1815 }
};
WriteResult writeResult = await docRef.SetAsync(user);
Console.WriteLine(writeResult.UpdateTime);Program.cs

Ruby

doc_ref = firestore.doc "users/alovelace"

doc_ref.set({
  first: "Ada",
  last:  "Lovelace",
  born:  1815
})

puts "Added data to the alovelace document in the users collection."quickstart.rb

Now add another document to the users collection. Notice that this document includes a key-value pair (middle name) that does not appear in the first document. Documents in a collection can contain different sets of information.

Java

DocumentReference docRef = db.collection("users").document("aturing");
// Add document data with an additional field ("middle")
Map<String, Object> data = new HashMap<>();
data.put("first", "Alan");
data.put("middle", "Mathison");
data.put("last", "Turing");
data.put("born", 1912);

ApiFuture<WriteResult> result = docRef.set(data);
System.out.println("Update time : " + result.get().getUpdateTime());Quickstart.java

Python

doc_ref = db.collection(u'users').document(u'aturing')
doc_ref.set({
    u'first': u'Alan',
    u'middle': u'Mathison',
    u'last': u'Turing',
    u'born': 1912
})snippets.py

Node.js

var aTuringRef = db.collection('users').doc('aturing');

var setAlan = aTuringRef.set({
  'first': 'Alan',
  'middle': 'Mathison',
  'last': 'Turing',
  'born': 1912
});index.js

Go

_, _, err = client.Collection("users").Add(ctx, map[string]interface{}{
	"first":  "Alan",
	"middle": "Mathison",
	"last":   "Turing",
	"born":   1912,
})
if err != nil {
	log.Fatalf("Failed adding aturing: %v", err)
}main.go

PHP

$docRef = $db->collection('users')->document('aturing');
$docRef->set([
    'first' => 'Alan',
    'middle' => 'Mathison',
    'last' => 'Turing',
    'born' => 1912
]);
printf('Added data to the aturing document in the users collection.' . PHP_EOL);add_data.php

C#

DocumentReference docRef = db.Collection("users").Document("aturing");
Dictionary<string, object> user = new Dictionary<string, object>
{
    { "First", "Alan" },
    { "Middle", "Mathison" },
    { "Last", "Turing" },
    { "Born", 1912 }
};
WriteResult writeResult = await docRef.SetAsync(user);
Console.WriteLine(writeResult.UpdateTime);Program.cs

Ruby

doc_ref = firestore.doc "users/aturing"

doc_ref.set({
  first:  "Alan",
  middle: "Mathison",
  last:   "Turing",
  born:   1912
})

puts "Added data to the aturing document in the users collection."quickstart.rb

Read data

To quickly verify that you've added data to Cloud Firestore, use the data viewer in the Firebase console.

You can also use the get method to retrieve the entire collection.

Java

// asynchronously retrieve all users
ApiFuture<QuerySnapshot> query = db.collection("users").get();
// ...
// query.get() blocks on response
QuerySnapshot querySnapshot = query.get();
List<QueryDocumentSnapshot> documents = querySnapshot.getDocuments();
for (QueryDocumentSnapshot document : documents) {
  System.out.println("User: " + document.getId());
  System.out.println("First: " + document.getString("first"));
  if (document.contains("middle")) {
    System.out.println("Middle: " + document.getString("middle"));
  }
  System.out.println("Last: " + document.getString("last"));
  System.out.println("Born: " + document.getLong("born"));
}Quickstart.java

Python

users_ref = db.collection(u'users')
docs = users_ref.get()

for doc in docs:
    print(u'{} => {}'.format(doc.id, doc.to_dict()))snippets.py

Node.js

db.collection('users').get()
    .then((snapshot) => {
      snapshot.forEach((doc) => {
        console.log(doc.id, '=>', doc.data());
      });
    })
    .catch((err) => {
      console.log('Error getting documents', err);
    });index.js

Go

iter := client.Collection("users").Documents(ctx)
for {
	doc, err := iter.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Failed to iterate: %v", err)
	}
	fmt.Println(doc.Data())
}main.go

PHP

$usersRef = $db->collection('users');
$snapshot = $usersRef->documents();
foreach ($snapshot as $user) {
    printf('User: %s' . PHP_EOL, $user->id());
    printf('First: %s' . PHP_EOL, $user['first']);
    if (!empty($user['middle'])) {
        printf('Middle: %s' . PHP_EOL, $user['middle']);
    }
    printf('Last: %s' . PHP_EOL, $user['last']);
    printf('Born: %d' . PHP_EOL, $user['born']);
    printf(PHP_EOL);
}
printf('Retrieved and printed out all documents from the users collection.' . PHP_EOL);get_all.php

C#

CollectionReference usersRef = db.Collection("users");
QuerySnapshot snapshot = await usersRef.SnapshotAsync();
foreach (DocumentSnapshot document in snapshot.Documents)
{
    Console.WriteLine("User: {0}", document.Id);
    Dictionary<string, object> documentDictionary = document.ToDictionary();
    Console.WriteLine("First: {0}", documentDictionary["First"]);
    if (documentDictionary.ContainsKey("Middle"))
    {
        Console.WriteLine("Middle: {0}", documentDictionary["Middle"]);
    }
    Console.WriteLine("Last: {0}", documentDictionary["Last"]);
    Console.WriteLine("Born: {0}", documentDictionary["Born"]);
    Console.WriteLine();
}Program.cs

Ruby

users_ref = firestore.col "users"
users_ref.get do |user|
  puts "#{user.document_id} data: #{user.data}."
endquickstart.rb

Next steps

Deepen your knowledge with the following topics:

Data model — Learn more about how data is structured in Cloud Firestore, including hierarchical data and subcollections.
Add data — Learn more about creating and updating data in Cloud Firestore.
Get data — Learn more about how to retrieve data.
Perform simple and compound queries — Learn how to run simple and compound queries.
Order and limit queries — Learn how to order and limit the data returned by your queries.

Before you begin

Create a Cloud Firestore in Native mode database

Set up authentication

GCP Console

Command line

Linux or macOS

Windows

Add the server client library to your app

Java

Python

Node.js

Go

PHP

C#

Ruby

Initialize Cloud Firestore

Java

Python

Node.js

Go

PHP

C#

Ruby

Add data

Java

Python

Node.js

Go

PHP

C#

Ruby

Java

Python

Node.js

Go

PHP

C#

Ruby

Read data

Java

Python

Node.js

Go

PHP

C#

Ruby

Next steps

Send feedback about...