#%RAML 1.0 DataType
displayName: build
description: |
    This resource type describes completed and in-progress builds.
    Much of the contextual data for a build is associated with the build request, and through it the buildset.

    .. note::

        The properties field of a build is only filled out if the `properties filterspec` is set.
        That means the ``property`` filter allows one to request properties through the Builds DATA API like so:

            * api/v2/builds?property=* (returns all properties)
            * api/v2/builds?property=propKey1&property=propKey2 (returns the properties that match the given keys)
            * api/v2/builds?property=propKey1&property=propKey2&limit=30 (filters combination)

        .. important::

            When combined with the ``field`` filter, for someone to get the build properties, they should ensure the **properties** field is set:

            * api/v2/builds?field=buildid&field=properties&property=workername&property=user


    Update Methods
    --------------

    All update methods are available as attributes of ``master.data.updates``.

    .. py:class:: buildbot.data.builds.Build

        .. py:method:: newBuild(builderid, buildrequestid, workerid)

            :param integer builderid: id of the builder performing this build
            :param integer buildrequestid: id of the build request being built
            :param integer workerid: id of the worker on which this build is performed
            :returns: (buildid, number) via Deferred

            Create a new build resource and return its ID.
            The state strings for the new build will be set to 'starting'.

        .. py:method:: setBuildStateString(buildid, state_string)

            :param integer buildid: the build to modify
            :param unicode state_string: new state string for this build

            Replace the existing state strings for a build with a new list.

        .. py:method:: finishBuild(buildid, results)

            :param integer buildid: the build to modify
            :param integer results: the build's results

            Mark the build as finished at the current time, with the given results.

properties:
    buildid:
        description: the unique ID of this build
        type: integer
    number:
        description: the number of this build (sequential for a given builder)
        type: integer
    builderid:
        description: id of the builder for this build
        type: integer
    buildrequestid:
        description: build request for which this build was performed, or None if no such request exists
        type: integer
    workerid:
        description: the worker this build ran on
        type: integer
    masterid:
        description: the master this build ran on
        type: integer
    started_at:
        description: time at which this build started
        type: date
    complete:
        description: |
            true if this build is complete.
            Note that this is a calculated field (from complete_at != None).
            Ordering by this field is not optimized by the database layer.
        type: boolean
    complete_at?:
        description: time at which this build was complete, or None if it's still running
        type: date
    properties?:
        description: a dictionary of properties attached to build.
        type: sourcedproperties
    results?:
        description: the results of the build (see :ref:`Build-Result-Codes`), or None if not complete
        type: integer
    state_string:
        description: a string giving detail on the state of the build.
        type: string
type: object
example:
    builderid: 10
    buildid: 100
    buildrequestid: 13
    workerid: 20
    complete: false
    complete_at: null
    masterid: 824
    number: 1
    results: null
    started_at: 1451001600
    state_string: created
    properties: {}