Firebase Data Connect client SDKs let you call your server-side queries andmutations directly from a Firebase app. You generate a custom client SDK inparallel as you design the schemas, queries and mutations you deploy to yourData Connect service. Then, you integrate methods from this SDK intoyour client logic.

As we've mentioned elsewhere, it's important to note thatData Connectqueries and mutations are not submitted by client code and executed on theserver. Instead, when deployed,Data Connect operations are stored onthe server like Cloud Functions. This means you need to deploy correspondingclient-side changes to avoid breaking existing users (for example, on older appversions).

That's whyData Connect provides you with a developer environment andtooling that lets you prototype your server-deployed schemas, queries and mutations.It also generates client-side SDKs automatically, while you prototype.

When you've iterated updates to your service and client apps, both server- andclient-side updates are ready to deploy.

What is the client development workflow?

If you followed theGet started, you wereintroduced to the overall development flow forData Connect. In thisguide, you'll find more detailed information about generating Swift SDKs fromyour schema and working with client queries and mutations.

To summarize, to use generated Swift SDKs in your client apps, you'll followthese prerequisite steps:

1. Add Firebase to youriOS app.

2. To use the generated SDK, configure it as a dependency in Xcode.

   In the Xcode top navigation bar, selectFile > Add Package Dependencies > Add Local, and choose the foldercontaining the generatedPackage.swift.

Then:

1. Develop your app schema.

2. Set up SDK generation:

   • With theAdd SDK to app button in our Data Connect VS Code extension
   • Byupdating yourconnector.yaml

3. Initialize your client code and import libraries.

4. Implement calls to queries and mutations.

5. Set up and use theData Connect emulator anditerate.

Generate your Swift SDK

Use theFirebase CLI to set upData Connect generated SDKs in your apps.Theinit command should detect all apps in the current folder and installgenerated SDKs automatically.

firebase init dataconnect:sdk

Update SDKs while prototyping

If you have Data Connect VS Code extension installed, it will always keep generatedSDKs up to date.

If you don't use Data Connect VS Code extension, you can use Firebase CLIto keep generated SDKs up to date.

firebasedataconnect:sdk:generate--watch

Generate SDKs in build pipelines

You can use the Firebase CLI to generate Data Connect SDKs in CI/CD build processes.

firebasedataconnect:sdk:generate

Initialize theData Connect iOS SDK

Initialize yourData Connect instance using the information youused to set up Data Connect (all available in theFirebase consoleData Connect tab).

Getting a connector instance

The code for your connector will be generated by theData Connect emulator. If your connector name ismovies and thepackage ismovies, as specified inconnector.yaml, thenretrieve the connector object by calling:

letconnector=DataConnect.moviesConnector

Implement queries and mutations

With the connector object, you can run queries and mutations as defined in theGraphQL source code. Suppose your connector has these operations defined:

mutationcreateMovie($title:String!,$releaseYear:Int!,$genre:String!,$rating:Int!){movie_insert(data:{title:$titlereleaseYear:$releaseYeargenre:$genrerating:$rating})}querygetMovieByKey($key:Movie_Key!){movie(key:$key){idtitle}}querylistMoviesByGenre($genre:String!){movies(where:{genre:{eq:$genre}}){idtitle}}

You can then create a movie as follows:

letmutationResult=tryawaitconnector.createMovieMutation.execute(title:"Empire Strikes Back",releaseYear:1980,genre:"Sci-Fi",rating:5)print("Movie ID:\(mutationResult.data.movie_insert.id)")

To retrieve a movie, you will use a query reference. All query refs areObservable publishers. Depending on the configured publisher (seeconnector.yaml),they either support the@Observable macro (iOS 17+) or implement theObservableObject protocol. The default, if none is specified, is the@Observable macro supported on iOS 17+.

In a SwiftUI view, you can bind the query results using the publisheddatavariable of the query ref and call the query'sexecute() method to updatethe data. Thedata variable will match the shape of data that was definedin your GQL query definition.

All retrieved results comply with theDecodable protocol. If you includedthe object's primary key in your GQL fetch, the objects are alsoIdentifiable,allowing you to use them in iterators.

structListMovieView:View{@StateObjectprivatevarqueryRef=connector.listMoviesByGenreQuery.ref(genre:"Sci-Fi")varbody:someView{VStack{Button{Task{do{tryawaitrefresh()}catch{print("Failed to refresh:\(error)")}}}label:{Text("Refresh")}// use the query results in a viewForEach(queryRef.data?.movies??[],id:\.self.id){movieinText(movie.title)}}}@MainActorfuncrefresh()asyncthrows{_=tryawaitqueryRef.execute()}}

letresultData=tryawaitDataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre:"Sci-Fi")

An app's schema cancontain enumerations,which can be accessed by yourGraphQL queries.

As an app's design changes, you may add new enum supported values. For example,imagine that later in your application’s lifecycle you decide to add aFULLSCREEN value to theAspectRatio enum.

In theData Connect workflow, you can use local development tooling toupdate your queries and SDKs.

However, before you release an updated version of your clients, older deployedclients may break.

Example resilient implementation

The generated SDK forces handling of unknown values as the generated enumscontain an_UNKNOWN value, and Swift enforces exhaustive switch statements.

do{letresult=tryawaitDataConnect.moviesConnector.listMovies.execute()ifletdata=result.data{formovieindata.movies{switchmovie.aspectratio{case.ACADEMY:print("academy")case.WIDESCREEN:print("widescreen")case.ANAMORPHIC:print("anamorphic")case._UNKNOWN(letunknownAspect):print(unknownAspect)}}}}catch{// handle error}

Prototype and test your iOS application

Instrument clients to use a local emulator

You can use theData Connect emulator, whether from theData Connect VS Code extension or from the CLI.

Instrumenting the app to connect to the emulator is the same for both scenarios.

letconnector=DataConnect.moviesConnector// Connect to the emulator on "127.0.0.1:9399"connector.useEmulator()// (alternatively) if you're running your emulator on non-default port:connector.useEmulator(port:9999)// Make calls from your app

Data types inData Connect SDKs

TheData Connect server represents common and custom GraphQL datatypes. These are represented in the SDK as follows.