Module: Google::Cloud::Firestore

Defined in:
lib/google/cloud/firestore.rb,
lib/google/cloud/firestore/batch.rb,
lib/google/cloud/firestore/query.rb,
lib/google/cloud/firestore/client.rb,
lib/google/cloud/firestore/errors.rb,
lib/google/cloud/firestore/filter.rb,
lib/google/cloud/firestore/convert.rb,
lib/google/cloud/firestore/service.rb,
lib/google/cloud/firestore/version.rb,
lib/google/cloud/firestore/generate.rb,
lib/google/cloud/firestore/field_path.rb,
lib/google/cloud/firestore/bulk_writer.rb,
lib/google/cloud/firestore/credentials.rb,
lib/google/cloud/firestore/field_value.rb,
lib/google/cloud/firestore/transaction.rb,
lib/google/cloud/firestore/watch/order.rb,
lib/google/cloud/firestore/rate_limiter.rb,
lib/google/cloud/firestore/resource_path.rb,
lib/google/cloud/firestore/promise/future.rb,
lib/google/cloud/firestore/query_listener.rb,
lib/google/cloud/firestore/query_snapshot.rb,
lib/google/cloud/firestore/watch/listener.rb,
lib/google/cloud/firestore/aggregate_query.rb,
lib/google/cloud/firestore/commit_response.rb,
lib/google/cloud/firestore/document_change.rb,
lib/google/cloud/firestore/query_partition.rb,
lib/google/cloud/firestore/watch/inventory.rb,
lib/google/cloud/firestore/collection_group.rb,
lib/google/cloud/firestore/bulk_commit_batch.rb,
lib/google/cloud/firestore/document_listener.rb,
lib/google/cloud/firestore/document_snapshot.rb,
lib/google/cloud/firestore/document_reference.rb,
lib/google/cloud/firestore/collection_reference.rb,
lib/google/cloud/firestore/query_explain_result.rb,
lib/google/cloud/firestore/bulk_writer_exception.rb,
lib/google/cloud/firestore/bulk_writer_operation.rb,
lib/google/cloud/firestore/bulk_writer_scheduler.rb,
lib/google/cloud/firestore/watch/enumerator_queue.rb,
lib/google/cloud/firestore/document_reference/list.rb,
lib/google/cloud/firestore/aggregate_query_snapshot.rb,
lib/google/cloud/firestore/collection_reference_list.rb,
lib/google/cloud/firestore/aggregate_query_explain_result.rb

Overview

Cloud Firestore

Cloud Firestore is a NoSQL document database built for automatic scaling, high performance, and ease of application development. While the Cloud Firestore interface has many of the same features as traditional databases, as a NoSQL database it differs from them in the way it describes relationships between data objects.

See Firestore Overview.

Defined Under Namespace

Modules: Promise Classes: AggregateQuery, AggregateQueryExplainResult, AggregateQuerySnapshot, Batch, BulkCommitBatchError, BulkWriter, BulkWriterError, BulkWriterException, BulkWriterOperationError, BulkWriterSchedulerError, Client, CollectionGroup, CollectionReference, CommitResponse, Credentials, DocumentChange, DocumentListener, DocumentReference, DocumentSnapshot, FieldPath, FieldValue, Filter, Query, QueryExplainResult, QueryListener, QueryPartition, QuerySnapshot, Transaction

Constant Summary collapse

VERSION = 
"3.1.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.firestore| ... } ⇒ Google::Cloud::Config

Configure the Google Cloud Firestore library.

The following Firestore configuration parameters are supported:

  • project_id - (String) Identifier for a Firestore project. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • quota_project - (String) The project ID for a project that can be used by client libraries for quota and billing purposes.
  • timeout - (Integer) Default timeout to use in requests.
  • endpoint - (String) Override of the endpoint host name, or nil to use the default endpoint.
  • emulator_host - (String) Host name of the emulator. Defaults to ENV["FIRESTORE_EMULATOR_HOST"]

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Firestore library uses.



164
165
166
167
168
 
# File 'lib/google/cloud/firestore.rb', line 164

def self.configure
  yield Google::Cloud.configure.firestore if block_given?

  Google::Cloud.configure.firestore
end

.new(project_id: nil, credentials: nil, scope: nil, timeout: nil, endpoint: nil, emulator_host: nil, database_id: nil, transport: nil, project: nil, keyfile: nil) ⇒ Google::Cloud::Firestore::Client

Creates a new object for connecting to the Firestore service. Each call creates a new connection.

For more information on connecting to Google Cloud see the Authentication Guide.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

Parameters:

  • project_id (String) (defaults to: nil) —

    Identifier for a Firestore project. If not present, the default project for the credentials is used.

  • credentials (Google::Auth::Credentials) (defaults to: nil) —

    A Google::Auth::Credentials object. (See Credentials) @note Warning: Passing a String to a keyfile path or a Hash of credentials is deprecated. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data.

    @example

    # The recommended way to provide credentials is to use the make_creds method # on the appropriate credentials class for your environment.

    require "googleauth"

    credentials = ::Google::Auth::ServiceAccountCredentials.make_creds( json_key_io: ::File.open("/path/to/keyfile.json") )

    firestore = Google::Cloud::Firestore.new( project_id: "my-project-id", credentials: credentials )

  • scope (String, Array<String>) (defaults to: nil) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

    The default scope is:

    • https://www.googleapis.com/auth/datastore
  • timeout (Integer) (defaults to: nil) —

    Default timeout to use in requests. Optional.

  • endpoint (String) (defaults to: nil) —

    Override of the endpoint host name. Optional. If the param is nil, uses the default endpoint.

  • emulator_host (String) (defaults to: nil) —

    Firestore emulator host. Optional. If the param is nil, uses the value of the emulator_host config.

  • database_id (String) (defaults to: nil) —

    Identifier for a Firestore database. If not present, the default database of the project is used.

  • transport (:grpc, :rest) (defaults to: nil) —

    Which transport to use to communicate with the server. Defaults to :grpc.

  • project (String) (defaults to: nil) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) (defaults to: nil) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/google/cloud/firestore.rb', line 95

def self.new project_id: nil,
             credentials: nil,
             scope: nil,
             timeout: nil,
             endpoint: nil,
             emulator_host: nil,
             database_id: nil,
             transport: nil,
             project: nil,
             keyfile: nil
  project_id ||= project || default_project_id
  scope ||= configure.scope
  timeout ||= configure.timeout
  endpoint ||= configure.endpoint
  emulator_host ||= configure.emulator_host
  database_id ||= configure.database_id
  transport ||= configure.transport

  if emulator_host
    project_id = project_id.to_s
    raise ArgumentError, "project_id is missing" if project_id.empty?

    service = Firestore::Service.new project_id, :this_channel_is_insecure, host: emulator_host,
                                     timeout: timeout, database: database_id, transport: transport
    return Firestore::Client.new service
  end

  credentials ||= keyfile || default_credentials(scope: scope)
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Firestore::Credentials.new credentials, scope: scope
  end

  if credentials.respond_to? :project_id
    project_id ||= credentials.project_id
  end
  project_id = project_id.to_s
  raise ArgumentError, "project_id is missing" if project_id.empty?

  service = Firestore::Service.new project_id, credentials, host: endpoint,
                                   timeout: timeout, database: database_id, transport: transport
  Firestore::Client.new service
end