---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Interact with table data in a ServiceNow instance

# Interact with table data in a ServiceNow instance {#ariaid-title1}

Release version: Yokohama  
Updated January 30, 2025  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read
Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI  
This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.  

## Summary of Interact with table data in a ServiceNow instance

The Mobile SDK enables ServiceNow customers to interact with data stored in their ServiceNow instance tables.
This interaction is facilitated through two main APIs:NowTableService()for direct REST Table API calls andNowGraphQLService()for executing GraphQL queries via the REST GraphQL API.
These APIs support authorized CRUD operations on records within ServiceNow tables, allowing flexible and secure data access and manipulation.
Show full answer Show less  

## Using NowGraphQLService to Interact with Tables

The **NowGraphQLService** class allows customers to construct and execute GraphQL queries on specified tables. It supports all CRUD operations within a single query and can return data from multiple tables in one call. Query execution can be handled via completion handlers, async/await, or (deprecated) Combine publishers.

Typical usage includes initializing the service with the instance URL and then executing queries asynchronously to fetch or manipulate data, for example retrieving the most recently published knowledge base articles. Proper user authorization is required for query execution.

## Using NowTableService to Interact with Tables

The **NowTableService** class offers comprehensive methods for CRUD operations on ServiceNow table records accessible to the logged-in user. It supports dot-walking on reference fields to access related table data and respects all Access Control Lists (ACLs) to enforce data security and authorization.

Results from CRUD methods can be obtained via async/await, completion handlers with result enumerations, or deprecated Combine publishers. The service supports two variations of methods: those returning raw data and those returning strongly typed Codable models, enabling customers to choose based on their data handling preferences.

For example, `createRecord()` inserts records with options to specify write and read configurations, and `update()` methods update records while optionally returning Codable models for type safety.

Initialization involves creating a **NowTableService** instance with the ServiceNow instance URL, handling success or failure asynchronously.

## Practical Benefits for ServiceNow Customers

* Enable secure and authorized interaction with ServiceNow table data directly from mobile applications using REST or GraphQL APIs.
* Perform complex queries and CRUD operations efficiently, including multi-table data retrieval via GraphQL.
* Leverage async/await for modern asynchronous programming or use completion handlers for callback-based workflows.
* Choose between raw data or strongly typed Codable models to fit application data handling needs.
* Respect ServiceNow security via ACL enforcement automatically applied in data access.

## Next Steps

ServiceNow customers should incorporate the NowData framework, initialize the appropriate service (NowGraphQLService or NowTableService) with their instance URL, and utilize the provided APIs for their application-specific data interactions. For detailed method references and code examples, customers can consult the NowTableService iOS API documentation.  
The Mobile SDK enables you to interact with data in tables that reside
on your ServiceNow instance. You can interact with this data through the
ServiceNow REST Table API using the NowTableService() API that directly calls the REST interface, or through the
NowGraphQLService() API that executes a specified GraphQL query against the
REST GraphQL API.
If you want to return data from multiple tables within a single call, you will need to use
the NowGraphQLService() API. If you need to interact with other ServiceNow REST APIs, see [Interact with the public REST API on a ServiceNow instance](https://servicenow-prod.fluidtopics.net/dwqkhHoxTbJGh6Mj23IWEw "The Mobile SDK provides functionality that enables iOS applications to call the public REST API on a ServiceNow instance.").

## Using NowGraphQLService to interact with ServiceNow
tables {#mobsdk-ios-interact_data_instance__section_kxm_wdf_hqb}

The [NowGraphQLService](https://servicenow-prod.fluidtopics.net/bvj4FDHjI7COjzFKxg8b1Q#NowGraphQLServiceiOSAPI "The NowGraphQLService class provides functions that enable you to make requests using GraphQL queries against data on your ServiceNow instance through its GraphQL REST API.") class provides methods that enable you to construct and execute
GraphQL queries on a specified table within your ServiceNow instance
if the logged in user has the proper authorization. You can define all CRUD operations
within your GraphQL query.  
NowGraphQLService supports fetching results for a query by returning a completion handler:

    func execute(_ query: GraphQLQuery, completion: @escaping (Result<Data, NowDataError>) → Void)

Through async/await:

    func execute(_ query: GraphQLQuery) async throws -> Data

Or, a [Combine](https://developer.apple.com/documentation/combine) publisher (which is currently deprecated):

    func publisher(for query: GraphQlQuery) → AnyPublisher<Data, NowDataError>

The following example shows how to import the NowData framework and then initialize a NowGraphQLService object that you can then use to interact with tables in your ServiceNow instance.

    // Import the NowData framework
    import NowData

    // Initialize a NowGraphQLService
    // The makeGraphQLService completion handler returns a result that wraps 
    // the NowGraphQLService upon success or error. 

    private func initializeGraphQLService(instanceUrl: URL) {
      makeGraphQLService(instanceUrl: instanceUrl) { [weak self] result in
        switch result {
        case .success(let service):
          self?.graphQLService = service
        case .failure(let error):
          debugPrint("Creating GraphQL service failed with error: \(error.localizedDescription)")
          self?.graphQLService = nil
        }
      }
    }

This example shows how to create an async function that fetches and publishes the most recently published KB articles.

    private func fetchArticles() async throws -> [Article] { 
        guard let graphQLService = graphQLService else { 
            throw ArticleListError.invalidGraphQLService 
        }         

        do {
            let data = try await graphQLService.execute(GraphQLQuery(query: recentlyPublishedQuery))
            let articles = try dataToArticleList(data)
        } catch let error as NowDataError {
            throw ArticleListError.fetchError(error)
        } catch {
            throw error
        }
    } 
      
    private let recentlyPublishedQuery = 
    """ 

    {
      GlideRecord_Query {
        kb_knowledge(queryConditions: "active=true^ORDERBYpublishedDESC" pagination: { limit: 10, offset: 0 }) {
          _results { 
            sys_id {
              value
            },
            number {
              displayValue
            },
            short_description {
              displayValue
            },
            author {
              displayValue
            }
            published {
              displayValue
            }
          }
        }
      }
    }
    """

## Using NowTableService to interact with ServiceNow tables {#mobsdk-ios-interact_data_instance__section_fgn_gy2_hqb}

The [NowTableService](https://servicenow-prod.fluidtopics.net/zNm3xxQusg8lk0wvl8vDKw#NowTableServiceiOSAPI "The NowTableService class provides functions that enable you to perform create, read, update, and delete operations on records of existing ServiceNow tables.") class provides methods to perform CRUD operations on the records in tables that reside on your ServiceNow instance. Through this interface you can directly access any of the records within any ServiceNow table for which the logged in user is authorized. NowTableService supports dot-walking for reference fields. For example, if a table contains a reference to the User table, the
dot-walked value `user.name` returns the name of the user.

When returning the requested data, all applicable Access Control Lists (ACLs) are applied to the data, which may result in fewer results than expected,
or authorization errors if the authenticated user does not have access rights to the specified table.

Most NowTableService methods provide three implementations for returning results data. One that uses
async/await, one that calls a completion handler with a Result enumeration, and one that returns a [Combine](https://developer.apple.com/documentation/combine) publisher, which is currently deprecated.

For example, all createRecord() methods insert a constructed record into a specified table, however, the

[NowTableService - createRecord(with fields: [FieldName: FieldValue], in tableName: String, writeOptions: FieldWriteOptions, configuration: FieldReadConfiguration, completion: @escaping (Result<Data, NowDataError>)](zNm3xxQusg8lk0wvl8vDKw#NTblServ-createRecord_S_O_O_O "Inserts the specified record in the specified table and then executes the completion handler after the record is saved.")

method calls a completion handler with a Result enumeration (the `.success` case contains the results as its associated
value).

The
[NowTableService - createRecord(with fields: [FieldName: FieldValue], in tableName: String, writeOptions: FieldWriteOptions? = nil, configuration: FieldReadConfiguration? = nil) async throws](zNm3xxQusg8lk0wvl8vDKw#NTblServ-createRecord-async_S_O_O "Inserts a record in the specified table that contains the specified fields.")

method performs an async/await function. While the

[NowTableService - createRecord(with fields: [FieldName: FieldValue], in tableName: String, writeOptions: FieldWriteOptions? = nil, configuration: FieldReadConfiguration? = nil)](zNm3xxQusg8lk0wvl8vDKw#NTblServ-createRecord_S_O_O "Inserts a record in the specified table that contains the specified fields.")`
`

method returns a Combine publisher, but is currently deprecated.

In addition, NowTableService provides two different implementations of CRUD methods, one that returns raw data, and one that
returns Codable models. For example, both the update() and updateRecord() methods update a specified record in a specified table, but the update() methods return a Codable
model and the updateRecord() methods return raw data. In some cases, Codable methods might be preferable, as a strongly typed Codable structure provides more flexibility than a collection of raw data
fields.  
The following example shows how to import the NowData framework and then initialize a NowTableService object that you can then use to interact with ServiceNow instance tables.

    // Import the NowData framework
    import NowData

    // Initialize a NowTableService
    // The makeTableService completion handler returns a result that wraps 
    // the NowTableService upon success or error. 

    makeTableService(instanceUrl: instanceUrl) { [weak self] result in
      guard let self = self else { return }
      
      switch result {
      case .success(let tableService):
        debugPrint("Successfully created a table service \(tableService)")
        self.tableService = tableService
      case .failure(let error):
        debugPrint("Creating table service failed with error: \(error.localizedDescription)")
      }
    }

For additional code examples using the available NowTableService methods, refer to the [NowTableService class - iOS](https://servicenow-prod.fluidtopics.net/zNm3xxQusg8lk0wvl8vDKw#NowTableServiceiOSAPI "The NowTableService class provides functions that enable you to perform create, read, update, and delete operations on records of existing ServiceNow tables.")`
`API documentation.