> ## Documentation Index > Fetch the complete documentation index at: https://insightsoftware.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Creates a data source field > Requires WRITE permission on the source or READ permission on the source and ROLE_EDIT_FORMULAS for derived field creation ## OpenAPI ````yaml /simba-embedded-analytics/docs/self-service-analytics/26.3/api-swagger/ssa-api-docs-26-3.json post /api/sources/{sourceId}/fields openapi: 3.1.0 info: title: Logi Composer Rest API description: >- The Composer REST API provides methods for retrieving, updating, and deleting Composer metadata. With the API endpoints, you can manage connections, data sources, accounts, groups, and users quickly and easily. ## Authentication This API supports the following authentication schemes: - **basicAuth** – HTTP Basic authentication using global administrator credentials (username and password). Required for most endpoints. - **trustedAccessAuth** – HTTP Basic authentication using Trusted Access client credentials. Use the **client ID** as the username and the **client secret** as the password. Required for Trusted Access token and session endpoints. - **bearerAuth** – HTTP Bearer token authentication. Supply a token previously obtained from a Trusted Access token endpoint (`/api/trusted-access/push/tokens` or `/api/trusted-access/pull/tokens`). contact: name: Logi Support url: https://help.insightsoftware.com email: logisupport@insightsoftware.com version: '1.0' servers: - url: http://10.2.4.166:8080/composer description: Generated server url security: - basicAuth: [] tags: - name: account-attributes description: Reserved Account attributes configuration - name: accounts description: Manage Accounts - name: accounts / admins description: Manage Account Administrators - name: accounts / users description: Manage Account Users - name: actions description: Manage Action Templates - name: activity description: Manages Activity Logging - name: alerts description: Manage Alerts - name: branding description: Manage branding configuration - name: branding-extentions description: Manage branding extensions (chart colors, etc.) - name: calendars description: (experimental) Manage calendars - name: comments description: Dashboard comments - name: connection-types description: Manage Connection Types - name: connections description: Manage Source Connections - name: connectors description: Manage Connectors - name: conversations description: Manage Workspace Conversations - name: customization description: Manage customization configuration - name: dashboard-conversion description: (experimental) Convert dashboards layout - name: dashboard-migration description: New Dashboards Migration API - name: dashboard-reports description: Manage Dashboard Reports - name: dashboard-sharing description: (experimental) Manage dashboard access level - name: dashboards description: Manage Dashboards - name: export description: Export Source Data - name: favorites description: Favorite Items - name: filter-sets description: Filter Visualizations Data - name: folders description: Manage folders - name: frontend / environment variables description: Get environment variables for frontend - name: global description: Manage global security configuration - name: group-membership description: Manages Group Membership - name: groups description: Manage User Groups - name: interactivity description: Dashboard interactivity - name: inventory description: Manage Composer Items - name: jobs description: List of available scheduler jobs - name: joins description: Manage joins metadata and suggestions - name: json-datasets description: Manage JSON datasets - name: kerberos description: Manage Kerberos Config - name: keyset description: Manage keysets - name: ldap description: Manage LDAP Configuration - name: license description: Manage Composer License - name: locale, currency, language description: Locale, currency, and language info - name: materialized-view description: (deprecated since 23.1) Manage Materialized Views - name: odata description: (experimental) Source Data Retrieval OData service - name: password-reset description: Self-service forgot-password flow - name: permissions description: Manage Permissions - name: Publish description: Publish Workspace Artifacts - name: quota description: Manage Quotas - name: recentlyAccessed description: Recently Accessed Elements - name: register description: User registration - name: saml description: Manage SAML - name: security description: Retrieve all sids info - name: self-service-reports description: Self Service Reports - name: sharing description: (experimental) Manage dashboard sharing - name: snapshots description: Create and manage entity snapshots - name: snippets description: (experimental) Manage snippets - name: sources description: Manage Sources - name: sources / cache-settings description: Manages sources cache settings - name: sources / custom-metrics description: Manage Source Custom Metrics - name: sources / dictionaries description: Manage Source Dictionaries - name: sources / fields description: Manage Source Fields - name: sources / global-settings description: Manages sources global settings - name: sources / migration description: Source Migration API - name: sources / preview and describe description: Source preview and describe - name: sources / raw data description: (experimental) Get source raw data - name: sources / security description: Manage Sources Security - name: sources / security / custom metrics description: (experimental) Manage Sources Custom Metric Security - name: sources / security / fields description: Manage Sources Fields Security - name: sources / security / row description: Manage Sources Row Security - name: sources / unique-key description: Manages sources unique key - name: sources / visual-types description: Manages source visual types - name: start-vis description: (experimental) Execute start-vis or meta request - name: stream description: Search stream sources - name: tags description: Manage tags - name: timezones description: Timezone Information - name: toggle description: Toggle Features - name: topics description: Manage topics - name: trusted-access-client description: Manage Trusted Access clients - name: trusted-access-session description: Manage user sessions via Trusted Access - name: trusted-access-token description: Manage Trusted Access tokens - name: uploads description: Manage Uploads - name: user description: Manage User - name: users description: Manage Users - name: users segregation description: Segregate users into tenants - name: version description: System version - name: visual-types description: Manage Visual Types - name: visuals description: Manage Visuals - name: visuals / migration description: New Visuals Migration API - name: workspaces description: Manage Workspaces paths: /api/sources/{sourceId}/fields: post: tags: - sources / fields summary: Creates a data source field description: >- Requires WRITE permission on the source or READ permission on the source and ROLE_EDIT_FORMULAS for derived field creation operationId: create parameters: - name: sourceId in: path required: true schema: type: string - name: suppressWarnings in: query description: >- The response to this API endpoint may return a validation error with a list of problems. Each problem has a level (ERROR, WARNING). Passing suppressWarnings=true will suppress all warnings and the request will succeed if there are no errors required: false schema: type: boolean default: false requestBody: content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/SourceFieldResource' required: true responses: '201': description: The field was created content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/SourceFieldResource' '400': description: Request is invalid content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/ErrorMessage' '401': description: The user must be logged in content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/ServletErrorMessage' '403': description: The user doesn't have privilege to perform the operation content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: The source wasn't found content: application/vnd.composer.v3+json: schema: $ref: '#/components/schemas/ErrorMessage' components: schemas: SourceFieldResource: type: object properties: origin: $ref: '#/components/schemas/FieldOriginResource' name: type: string description: >- Unique identifier of the field within the source across all fields and custom metrics. It's immutable and may be specified in create request only. It will be generated if it's missing in the request example: field_name maxLength: 255 minLength: 0 pattern: ^[\p{L}_][\p{L}_\p{N}\.]*$ label: type: string description: >- User visible representation of the field. It will be generated if it's missing in the request example: Field Label maxLength: 255 minLength: 0 visible: type: boolean description: Whether the custom metric should be visible to users on a visual defaultMetric: type: string description: >- Data author can control default metric selected for this field. All metric pickers will choose this metric by default. Possible values: AVG/MIN/MAX/SUM/DISTINCT_COUNT/COUNT Default value: COUNT for ATTRIBUTES and SUM for NUMBER enum: - avg - min - max - sum - stddev_pop - stddev_samp - var_pop - var_samp - distinct_count - last_value - first_value - count - calc - percentile - median - listagg dataType: type: string description: >- Data type of the field. It’s detected automatically based on the field origin if it wasn't defined enum: - ATTRIBUTE - NUMBER - INTEGER - TIME - TEXT - HIERARCHY - 'NULL' format: $ref: '#/components/schemas/FieldFormatResource' description: Format of the field value display statistics: $ref: '#/components/schemas/StatisticsConfigurationResource' description: Field statistics configuration facetFiltering: $ref: '#/components/schemas/FacetFilteringResource' description: >- Facet filtering cofiguration. Available only for sources with TEXT_SEARCH feature granularity: type: string deprecated: true description: >- The minimum time granularity of this field. Composer optimizes queries based on this field. Also, it controls allowed granularities on group by time picker. It is auto detected based on the sample from the data set if it’s missed in the create request enum: - MILLISECOND - SECOND - MINUTE - HOUR - DAY - WEEK - MONTH - QUARTER - YEAR disabledCapabilities: type: array description: List of disabled field capabilities items: type: string fieldMetadata: type: object additionalProperties: type: string description: Field metadata as a JSON blob of key-value pairs rawFormatSupportTimeGroup: type: boolean deprecated: true fieldName: type: string deprecated: true description: >- Deprecated legacy property, which duplicates 'name' parameter. Will be removed at 23.3 originalFieldName: type: string deprecated: true description: >- Deprecated legacy property, which duplicates 'origin.nativeOrigin.originalName' parameter. Will be removed at 23.3 required: - origin ErrorMessage: type: object description: Generic error message properties: error: type: string details: type: string message: type: string path: type: string status: type: string code: type: string errorCode: type: string timestamp: type: string problems: type: array items: $ref: '#/components/schemas/ProblemResource' ServletErrorMessage: type: object description: Generic servlet error message properties: timestamp: type: string format: date-time status: type: integer format: int32 error: type: string message: type: string path: type: string FieldOriginResource: type: object description: >-

Field origin. Each of the origin types corresponds to it’s own field definition block:

properties: type: type: string enum: - NATIVE - DERIVED - HIERARCHY nativeOrigin: $ref: '#/components/schemas/NativeOriginResource' description: >- Defines a native field that is stored in the database. It’s required if origin.type = NATIVE derivedOrigin: $ref: '#/components/schemas/DerivedOriginResource' description: >- Defines derived field that can be calculated based on other fields. It’s required if origin.type = DERIVED hierarchyOrigin: $ref: '#/components/schemas/HierarchyOriginResource' description: >- Defines the hierarchy field. It’s required if origin.type = HIERARCHY required: - type FieldFormatResource: type: object description: >-

Field format. Each of the format blocks applicable only for certain data types:

There is no format for ATTRIBUTE, TEXT and HIERARCHY fields properties: time: $ref: '#/components/schemas/SourceTimeFormatResource' number: $ref: '#/components/schemas/NumberFormatResource' url: $ref: '#/components/schemas/UrlFormatResource' StatisticsConfigurationResource: type: object properties: override: $ref: '#/components/schemas/StatisticsOverrideResource' description: >- Statistics override. By default statistics are loaded from the data source and cached in QE cacheEnabled: type: boolean description: >- Each statistics request is cached on the QE side. If your data set has often changed data and is fast enough to process min, max and distinctValues on each their use you may disable statistics cache for this field refreshable: type: boolean description: >- There is an ability to define schedule for statistics refresh if cache is enabled. By default all time fields will be refresh according to the defined schedule. If you want to disable/enable automatic refresh for this field, you may use this flag. It doesn't have an effect if cache is disabled or override is defined lookup: $ref: '#/components/schemas/StatisticsLookupResource' cardinality: type: integer format: int32 FacetFilteringResource: type: object properties: enabled: type: boolean description: Is this field allowed to be used for facet filtering order: type: integer format: int32 description: The order of this field to appear for facet filtering minimum: 1 ProblemResource: type: object properties: name: type: string message: type: string level: type: string enum: - ERROR - WARNING dependencies: type: object additionalProperties: $ref: '#/components/schemas/ObjectUsageResource' NativeOriginResource: type: object properties: originalName: type: string description: Original field name as it’s in the database example: field_name maxLength: 255 minLength: 0 originalType: type: string description: Original field type as it’s in the database enum: - ATTRIBUTE - INTEGER - NUMBER - TIME - TEXT - BOOLEAN - 'NULL' - HIERARCHY - CHRONO_DATETIME example: TIME dataEntityId: type: string description: Defines the data entity to look for the field example: data_entity_1 maxLength: 255 minLength: 0 rawFormat: type: object additionalProperties: type: string description: >- Defines information required for connector specific to process request with this field. Don't try to compose it manually. You should either copy field definition with it or leave this field empty and Composer will fill it by himself by doing an additional call to the connector metaFlags: type: array description: Defines list of meta flags reported by the connector for this field items: type: string enum: - PLAYABLE - ANALYZED - RAW_DATA_ONLY - UNIQUE - GROUP_ONLY - PARTITION - NO_RAW_DATA - MULTI_VALUED - SYSTEM uniqueItems: true partitionedBy: $ref: '#/components/schemas/PartitionedByResource' description: >- Partitioning configuration defines partitioned field and func we should apply to the current field get partitioned value. Both fields are required if this block is defined. Example:

create table table_name ( id int, timestamp string, name string ) partitioned by (year string) Let’s assume our current field is timestamp. To define partitioning relation we should define partitionedBy block as>{ "field": "year", "function": "TIME" }

This example assumes that year field in composer has YEAR granularity required: - originalName DerivedOriginResource: type: object properties: expression: type: string description: >- Expression that should be evaluated at the row level to get value of this field. This expression may refer native fields and other derived fields and use supported functions. List of functions can be retrieved using syntax endpoint example: sales * 100 calendarId: type: string description: Id of the calendar for the field expression result referencedFieldNames: type: array items: type: string HierarchyOriginResource: type: object properties: labelField: type: string description: >- Field that contains label to display on the visualization instead of hierarchical value maxLength: 255 minLength: 0 childParent: $ref: '#/components/schemas/ChildParentResource' required: - childParent SourceTimeFormatResource: type: object description: Time format resource with deprecated granularity setting properties: granularity: type: string deprecated: true description: Deprecated, use 'SourceFieldResource.granularity' instead enum: - MILLISECOND - SECOND - MINUTE - HOUR - DAY - WEEK - MONTH - QUARTER - YEAR timeZone: type: string description: Time zone used for displaying this field in IANA format example: UTC options: $ref: '#/components/schemas/TimeFieldFormatOptionsResource' description: (experimental) Time field format options NumberFormatResource: type: object description: Number display format representation properties: type: type: string description: Number format type enum: - PLAIN - CURRENCY - PERCENTAGE - COMPUTER_STORAGE - SCIENTIFIC_NOTATION - RATIO decimals: type: integer format: int32 description: Decimal place example: 2 maximum: 9 minimum: 0 separator: type: boolean description: Use 1000 separator negative: type: string description: Negative display enum: - SIGNED - PARENTHESIZED standardUnit: type: string description: Generic unit multiple enum: - NONE - THOUSANDS - MILLIONS - BILLIONS - TRILLIONS storageUnit: type: string description: Storage unit multiple enum: - BYTES - KILOBYTES - MEGABYTES - GIGABYTES - TERABYTES - PETABYTES - EXABYTES currencyCode: type: string description: Currency code example: USD required: - type UrlFormatResource: type: object properties: type: type: string description: (experimental) Type for url formatting enum: - LINK - IMG - NONE src: type: string description: (experimental) Source for url width: type: integer format: int32 height: type: integer format: int32 required: - type StatisticsOverrideResource: type: object properties: min: type: number description: >- Min override is applicable for NUMBER and TIME fields. In case of TIME field min is milliseconds. If min is not defined actual value will be calculated on the data store side max: type: number description: >- Max override is applicable for NUMBER and TIME fields. In case of TIME field max is milliseconds. If max is not defined actual value will be calculated on the data store side distinctValues: type: array description: >- Defines custom values to show in filter panel. If it’s not defined actual values will be loaded from the data store. This field can be set to empty array [] to define that only custom values is allowed in filter panel for this field items: {} StatisticsLookupResource: type: object properties: raw: $ref: '#/components/schemas/StatisticsLookupRawResource' required: - raw ObjectUsageResource: type: object properties: hasOtherUsages: type: boolean accessible: type: array items: $ref: '#/components/schemas/AccessibleObjectUsageResource' PartitionedByResource: type: object properties: field: type: string maxLength: 255 minLength: 0 function: type: string enum: - MURMUR3_HASH - MURMUR3_HASH_1024 - AOL_MURMUR3_HASH - TIME required: - field - function ChildParentResource: type: object properties: childField: type: string maxLength: 255 minLength: 0 parentField: type: string maxLength: 255 minLength: 0 required: - childField - parentField TimeFieldFormatOptionsResource: type: object properties: second: type: string description: (experimental) Second time field formatting setting enum: - NUMERIC - TWO_DIGIT minute: type: string description: (experimental) Minute time field formatting setting enum: - NUMERIC - TWO_DIGIT hour: type: string description: (experimental) Hour time field formatting setting enum: - NUMERIC - TWO_DIGIT day: type: string description: (experimental) Day time field formatting setting enum: - NUMERIC - TWO_DIGIT - NARROW - SHORT - NONE weekday: type: string description: (experimental) Weekday time field formatting setting enum: - LONG - SHORT - NARROW - NONE week: type: string description: (experimental) Week time field formatting setting enum: - TWO_DIGIT - NARROW - RANGE - NUMERIC - WEEK_START - WEEK_END - NONE month: type: string description: (experimental) Month time field formatting setting enum: - NUMERIC - TWO_DIGIT - LONG - SHORT - NARROW - NONE quarter: type: string description: (experimental) Quarter time field formatting setting enum: - TWO_DIGIT - RANGE - NARROW - NUMERIC - NONE year: type: string description: (experimental) Year time field formatting setting enum: - NUMERIC - TWO_DIGIT - NARROW - SHORT - NONE dayOfYear: type: string description: (experimental) Day time field formatting setting enum: - NUMERIC - TWO_DIGIT - SHORT - NONE hour12: type: boolean description: >- (experimental) Enable/disable 12-hour time format. It will be selected automatically if nothing is selected StatisticsLookupRawResource: type: object properties: dataEntityId: type: string originalFieldName: type: string required: - dataEntityId - originalFieldName AccessibleObjectUsageResource: type: object properties: id: type: string name: type: string type: type: string enum: - SOURCE - MATERIALIZED_VIEW - KEY_SET - VISUAL - DASHBOARD - IN_DASHBOARD_VISUAL - SNIPPET - REPORT - FILTER_SET - DERIVED_FIELD - CUSTOM_METRIC - FIELD_LINK - ROW_SECURITY_FILTER - ACTION - SOURCE_JOIN - HIERARCHY - PARTITION - GLOBAL_FILTER - UNIQUE_KEY - TIME_CONTROL parent: $ref: '#/components/schemas/AccessibleObjectUsageResource' securitySchemes: basicAuth: type: http description: >- HTTP Basic authentication using global administrator credentials (username and password). scheme: basic ````