Stream - Scoped, Global

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：30分

    • The Stream API provides methods to interact with a stream of items such as records. For example, you can use the forEach() method to update the state of each record in a stream returned by the GlideQuery API.

    You can get a Stream object in these ways:

    • Instantiate a Stream object using the constructor.
    • Return a Stream object from the GlideQuery.select() method. For more information, see GlideQuery.

    This method is static and does not require an instance of the class: fromArray().

    Use the Stream API in scoped or global server-side scripts. This API requires the GlideQuery [com.sn_glidequery] plugin.

    Implementation

    This API can work with the GlideQuery and Optional APIs in a builder pattern where the method calls chain together, each method building on the returned result of the previous method. Use methods to define the attributes of the query. The methods do not execute until you call a terminal method, a method that returns a query result, allowing you to define the requirements of the query before executing it.

    If the query returns a single record, the system wraps the result in an Optional object. If the query returns a stream of records, the system wraps the result in a Stream object. These objects let you manage the result using a set of methods in each API.

    For example, this script performs a query on the Task table, groups the records by priority, and returns each priority that has total reassignments greater than four.

    var query = new global.GlideQuery('task')
    .where('active', true) //Returns new GlideQuery object with a "where" clause.
    .groupBy('priority') //Returns new GlideQuery object with a "group by" clause.
    .aggregate('sum', 'reassignment_count') //Returns new GlideQuery object with a "sum(reassignment_count)" clause.
    .having('sum', 'reassignment_count', '>', 4) //Returns new GlideQuery object with a "having reassignment_count > 4" clause.
    .select() //Returns a stream of records wrapped in a Stream object.  
    .forEach(function (priority){ //Terminal method in the Stream class that executes the query and returns the result. 
      gs.info("Priority " + priority.group.priority + ": " + priority.sum.reassignment_count + " reassignments");
    });
    Output:
    Priority 1: 11 reassignments
Priority 3: 6 reassignments
Priority 5: 5 reassignments

    Terminal methods

    For performance reasons, a query only fetches data when you call a terminal method. These are the terminal methods from the Stream class:

    Stream - Stream(Function nextFn)

    Instantiates a Stream object.

    Instead of using this constructor, you can return a Stream object based on a query using the GlideQuery API.

    表 : 1. Parameters
    Name Type Description
    nextFn Function A function that retrieves the next item in the stream.

    This example shows you how to create a Stream object based on a random number generator. Make sure to include the limit() method to avoid creating an infinite loop.

    new Stream(Math.random)
   .map(Math.round)
   .map(function (num) { 
      return num === 1 ? 'heads' : 'tails'; 
   })
   .limit(10)
   .forEach(gs.info)

    Output:

    *** Script: tails
*** Script: heads
*** Script: tails
*** Script: heads
*** Script: tails
*** Script: heads
*** Script: tails
*** Script: tails
*** Script: tails
*** Script: tails

    Stream - chunk(Number count)

    Returns results in batches of arrays, each containing the number of records passed to the method.

    表 : 2. Parameters
    Name Type Description
    count Number Number of records in each array returned from the stream.
    表 : 3. Returns
    Type Description
    Stream Object used to interact with a stream of items such as records.

    This example shows how to query a table and chunk the result into batches of arrays.

    var chunkResult = new GlideQuery('cmdb_ci_hardware')
    .select('asset', 'purchase_date')
    .limit(10)
    .chunk(5) //Returns arrays of 5 sys_ids at a time
    .forEach(function (chunk){ 
        gs.info(JSON.stringify(chunk, null, 2)); 
    });

    Output:

    *** Script: [
  {
    "asset": "2fa9680d3790200044e0bfc8bcbe5dfb",
    "purchase_date": "2022-02-28",
    "sys_id": "2ba9680d3790200044e0bfc8bcbe5dfc"
  },
  {
    "asset": "73c1fa8837f3100044e0bfc8bcbe5ded",
    "purchase_date": "2017-12-05",
    "sys_id": "b4fd7c8437201000deeabfc8bcbe5dc1"
  },
  {
    "asset": "cbc1ba8837f3100044e0bfc8bcbe5dad",
    "purchase_date": "2017-12-05",
    "sys_id": "25fd3c8437201000deeabfc8bcbe5dea"
  },
  {
    "asset": "8fc1ba8837f3100044e0bfc8bcbe5da9",
    "purchase_date": null,
    "sys_id": "108a9205c611227500786e160f9d343e"
  },
  {
    "asset": "27c1fa8837f3100044e0bfc8bcbe5dd8",
    "purchase_date": "2017-06-06",
    "sys_id": "a9a2d111c611227601fb37542399caa8"
  }
]
*** Script: [
  {
    "asset": "93c1fa8837f3100044e0bfc8bcbe5d30",
    "purchase_date": "2017-12-05",
    "sys_id": "6b43105c37301000deeabfc8bcbe5db2"
  },
  {
    "asset": "a2c0b1213784200044e0bfc8bcbe5de3",
    "purchase_date": "2017-12-05",
    "sys_id": "aac0b1213784200044e0bfc8bcbe5de3"
  },
  {
    "asset": "33c1fa8837f3100044e0bfc8bcbe5def",
    "purchase_date": "2017-12-05",
    "sys_id": "d0e8761137201000deeabfc8bcbe5da7"
  },
  {
    "asset": "53c1fa8837f3100044e0bfc8bcbe5d1f",
    "purchase_date": "2017-12-05",
    "sys_id": "53fdbc8437201000deeabfc8bcbe5d10"
  },
  {
    "asset": "f1c031213784200044e0bfc8bcbe5de0",
    "purchase_date": "2017-12-05",
    "sys_id": "71c031213784200044e0bfc8bcbe5de1"
  }
]

    This example shows how to create a child query using batches of IDs. When you call the flatMap() method after using the chunk() method, the system iterates over the batch of records instead of each individual record.

    var chunkResult = new global.GlideQuery('cmdb_ci_hardware')
    .select('sys_id')
    .map(function (device) { return device.sys_id; })
    .chunk(5) //Returns arrays of 5 sys_ids at a time
    .flatMap(function (deviceIds) {
        return new GlideQuery('cmdb_sam_sw_install')
            .where('installed_on', 'IN', deviceIds)
            .select('software_model', 'installed_on');
    })

gs.info(JSON.stringify(chunkResult));

    Stream - every(Function predicate)

    Applies a predicate function to every item in the Stream object. If the predicate returns true for every item in the stream, the method returns true. If the predicate returns false for any item in the stream, the method returns false.

    表 : 4. Parameters
    Name Type Description
    predicate Function Predicate function to apply to every record or item inside the Stream object. The function must take each item in the stream as input and return a boolean.
    表 : 5. Returns
    Type Description
    Boolean

    Flag that indicates whether the predicate function returns true for every item in the stream.

    Valid values:
    • true: The predicate function returns true for every item in the stream.
    • false: The predicate function does not return true for every item in the stream.

    This example shows how to apply a predicate function to every item in a stream.

    var hasOnlyShortDescriptions = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .every(function (t) { 
       return t.description.length < 10; 
       });

gs.info(hasOnlyShortDescriptions);

    Output:

    false

    Stream - filter(Function predicate)

    Applies a predicate function to each item in the Stream object. If the predicate returns true, the method returns the stream. If the predicate returns false, it returns an empty Stream object.

    For better performance, use the where(), whereNotNull(), and whereNull() methods in the GlideQuery class instead of this method where possible. See GlideQuery.

    表 : 6. Parameters
    Name Type Description
    predicate Function Predicate function to apply to every record or item inside the Stream object. The function must take each item in the stream as input and return a boolean.
    表 : 7. Returns
    Type Description
    Stream Object used to interact with a stream of items such as records.

    This example shows how to check all records in the Task table against a defined filter. If the records match the filter, the system returns the stream of records. Otherwise, it returns an empty Stream object.

    var shoutingTasks = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .filter(function (task) { 
       return task.description.toUpperCase() === task.description; 
   })

    Stream - find(Function predicate)

    Returns the first record or item in the Stream object that matches the predicate function. If no predicate function is provided, then the method returns the first record or item in the Stream.

    表 : 8. Parameters
    Name Type Description
    predicate Function Optional. Predicate function to apply to the items inside the Stream object. The function must take each item in the stream as input and return a boolean.
    表 : 9. Returns
    Type Description
    Optional Object containing the returned record.

    This example shows how to return the first record from the stream.

    var UserOptional = new global.GlideQuery('sys_user')
   .where('active', true)
   .where('company.name', 'ServiceNow')
   .select()
   .find()
   .map(function (user) { 
      return JSON.stringify(user); 
   })

gs.info(UserOptional);

    Output:

    Optional<{"sys_id":"babb4639b76233004fbc2089ee11a97f"}>

    Stream - flatMap(function fn)

    Applies a function to every item in a stream. Returns another stream that you can iterate over.

    Use this method instead of map() if the function returns a second stream of records.

    表 : 10. Parameters
    Name Type Description
    fn Function Function to apply to the result of the query that returns a Stream object.
    表 : 11. Returns
    Type Description
    Stream Object containing the stream of records updated after applying the function.

    This example shows you how to query the User table and then create a child query from the result. This example executes an N+1 query, which can cause performance issues. Avoid this use case in a production environment.

    var records = new global.GlideQuery('sys_user')
   .where('last_login', '>', '2015-12-31')
   .select('first_name', 'last_name')
   .flatMap(function (u) {
      return new global.GlideQuery('task')
           .where('closed_by', u.sys_id)
           .select('closed_at', 'description')
           .map(function (t) {
                return {
                    first_name: u.first_name,
                    last_name: u.last_name,
                    description: t.description,
                    closed_at: t.closed_at
                 };
           });
      })
   .limit(5)
   .toArray(100);

gs.info(JSON.stringify(records));

    Output:

    [
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:14:56"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:43"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-06-15 06:59:05"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:33"
   },
   {
      "first_name":"System",
      "last_name":"Administrator",
      "description":null,
      "closed_at":"2020-08-23 13:07:14"
   }
]

    Stream - forEach(Function fn)

    Applies the specified function to each record or item in the stream.

    表 : 12. Parameters
    Name Type Description
    fn Function Function to apply to each item in the stream.
    表 : 13. Returns
    Type Description
    None

    This example shows you how to print the result of each item in the stream.

    var firstNames = new global.GlideQuery('sys_user')
   .select('first_name')
   .forEach(function (u) { 
      gs.debug(u.first_name); 
   });

    Output:

    *** Script: [DEBUG] survey
*** Script: [DEBUG] Lucius
*** Script: [DEBUG] Jimmie
*** Script: [DEBUG] Melinda
*** Script: [DEBUG] Jewel
*** Script: [DEBUG] Sean
*** Script: [DEBUG] Jacinto
*** Script: [DEBUG] Krystle
*** Script: [DEBUG] Billie
*** Script: [DEBUG] Christian
*** Script: [DEBUG] Naomi
...

    Stream - fromArray(Object arr)

    Returns a Stream object that contains the values from the provided array.

    注:
    This method is static. You do not need an instance of the class to use this method.
    表 : 14. Parameters
    Name Type Description
    arr Array Array of values to create the stream from.
    表 : 15. Returns
    Type Description
    Stream Object used to interact with a stream of items such as records.

    This example shows how to create a Stream object containing an array of values.

    var nameStream = Stream.fromArray(['Bob', 'Sue', 'Sam'])
   .map(function (name) { 
      return name.toUpperCase(); 
   })
   .toArray(3);

gs.info(JSON.stringify(nameStream));

    Output:

    ["BOB","SUE","SAM"]

    Stream - limit(Number count)

    Limits the number of results returned by the stream.

    For better performance, use the limit() method in the GlideQuery class where possible. See GlideQuery. You may need to use this method to limit results with the Stream.flatMap() method.

    表 : 16. Parameters
    Name Type Description
    count Number Number of records to return.
    表 : 17. Returns
    Type Description
    Stream Object used to interact with a stream of items such as records.

    This example shows you how to limit the results returned from the Stream.flatMap() method.

    var records = new global.GlideQuery('sys_user')
   .where('last_login', '>', '2015-12-31')
   .select('first_name', 'last_name')
   .flatMap(function (u) {
      return new GlideQuery('task')
           .where('closed_by', u.sys_id)
           .select('closed_at', 'description')
           .map(function (t) {
                return {
                    first_name: u.first_name,
                    last_name: u.last_name,
                    description: t.description,
                    closed_at: t.closed_at
                 };
           });
      })
   .limit(5)
   .forEach(function (task){
      gs.info(JSON.stringify(task, null, 2));
   });

    Output:

    *** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:16"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:22"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:27"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:31"
}
*** Script: {
  "first_name": "System",
  "last_name": "Administrator",
  "description": null,
  "closed_at": "2021-10-04 13:40:54"
}

    Stream - map(Function fn)

    Applies a function to each item in a stream and returns the updated Stream object.

    表 : 18. Parameters
    Name Type Description
    fn Function Function to apply to the result of the query that takes the each item in the stream as input.
    表 : 19. Returns
    Type Description
    Stream Object containing the stream of records updated after applying the function.

    This example shows you how to apply a function to every item in the stream.

    var users = new global.GlideQuery('sys_user')
   .whereNotNull('first_name')
   .select('first_name')
   .map(function (u) { 
      return u.first_name.toUpperCase(); 
   })
   .toArray(100);

gs.info(JSON.stringify(users));

    Output:

    [
   "SURVEY",
   "LUCIUS",
   "JIMMIE",
   "MELINDA",
   "JEWEL",
   "SEAN",
   "JACINTO",
   "KRYSTLE",
   "BILLIE",
   "CHRISTIAN",
   ...
]

    Stream - reduce(function reducerFn, Any initialValue)

    Executes a reducer function on each item in the stream, resulting in single output value.

    This method is similar to the native JavaScript reduce() method. For more information, see w3schools documentation.

    表 : 20. Parameters
    Name Type Description
    reducerFn Function Function to apply to each item in the stream that reduces the stream to a single value. This function must take two arguments:
    • acc: Accumulator that accumulates all values returned by the function.
    • cur: Current item being accumulated in the array.
    initialValue Any Value passed to the function as the initial value.
    表 : 21. Returns
    Type Description
    Any Accumulated total of all items returned by the reducer function.

    This example shows you how to return the record with the longest name from the User table.

    var longestName = new global.GlideQuery('sys_user')
   .whereNotNull('first_name')
   .select('first_name')
   .reduce(function (acc, cur) {
       return cur.first_name.length > acc.length
           ? cur.first_name
           : acc;
       }, '');

gs.info(JSON.stringify(longestName));

    Output:

    "ATF_TestItilUser1"

    Stream - some(Function predicate)

    Applies a predicate function, a function that takes a single value and returns true or false, to each item in the stream. If the predicate returns true for any item in the stream, the method returns true.

    表 : 22. Parameters
    Name Type Description
    predicate Function Predicate function to apply to the items inside the Stream object. Must return a Boolean value.
    表 : 23. Returns
    Type Description
    Boolean

    Flag that indicates whether the predicate function returned true for an item in the stream.

    Valid values:
    • true: The predicate function returned true for an item in the stream.
    • false: The predicate function did not return true for an item in the stream.

    This example shows how to check whether any descriptions in the Task table are over 1,000 characters long.

    var hasLongDescriptions = new global.GlideQuery('task')
   .whereNotNull('description')
   .select('description')
   .some(function (t) { 
      return t.description.length > 1000; 
   });


gs.info(hasLongDescriptions);

    Output:

    false

    Stream - toArray(Number count)

    Returns an array containing the given number of items from the stream.

    表 : 24. Parameters
    Name Type Description
    count Number The maximum number of items from the stream to return in the array.
    表 : 25. Returns
    Type Description
    Array Array containing the given number of items from the stream.

    This example shows you how to transform a stream of records into a JavaScript array.

    var users = new global.GlideQuery('sys_user')
    .limit(10)
    .select('first_name', 'last_name')
    .toArray(50);

gs.info(JSON.stringify(users));

    Output:

    [
   {
      "first_name":"Jewel",
      "last_name":"Agresta",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d64"
   },
   {
      "first_name":"Sean",
      "last_name":"Bonnet",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d6d"
   },
   {
      "first_name":"Jacinto",
      "last_name":"Gawron",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d76"
   },
   {
      "first_name":"Krystle",
      "last_name":"Stika",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d7f"
   },
   {
      "first_name":"Billie",
      "last_name":"Cowley",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d88"
   },
   {
      "first_name":"Christian",
      "last_name":"Marnell",
      "sys_id":"02826bf03710200044e0bfc8bcbe5d91"
   }
]