String

Generates text: random characters, dictionary words, sentences, or values from a list.

Use it for a text column that is not a name, an identifier or a date, such as a code, a description, a comment or a status. mode sets how the text is generated:

Random characters of a set length, such as a code, is Random.
One or more dictionary words, such as a product name, is Word.
One or more sentences, such as a description, is Sentence.
Values from a fixed list, such as a status, is Lookup.

For a person's name, use Name or Person. For a code with a fixed format, such as an account number, use Identifier.

Sub-field: value, mapped to a text column such as VarChar.

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Properties

Property	Type	Default	Description
`beginsWith`	`string[]?`	none	The first letters a word can start with, one letter per entry. `Word` only.
`caseOutput`	`CaseOutput`	`"None"`	The case of the generated text. Not supported in `Lookup`.
`language`	`string`	`"English"`	The language of the words and sentences, or the alphabet of the characters in `Random` mode. See Languages.
`lookupValues`	`LookupValue[]`	none	The values for `Lookup` mode. Required in that mode.
`map`	`object`	required	Maps the `value` sub-field to a destination column. See Building a Request.
`maxLength`	`integer?`	none	In `Random`, the maximum number of characters, and required. In `Word`, the maximum length of a word.
`maxSentences`	`integer?`	none	The maximum number of sentences in a value. Set together with `minSentences`. `Sentence` only.
`maxWords`	`integer?`	none	The maximum number of words in a value. Set together with `minWords`. `Word` only.
`minLength`	`integer?`	`1` in `Random`	In `Random`, the minimum number of characters. In `Word`, the minimum length of a word, with no minimum when it is not set. Must be at least 1.
`minSentences`	`integer?`	none	The minimum number of sentences in a value. Set together with `maxSentences`. Without either, a value is one sentence. `Sentence` only.
`minWords`	`integer?`	none	The minimum number of words in a value. Set together with `maxWords`. Without either, a value is one word. `Word` only.
`mode`	`"Random"` / `"Word"` / `"Sentence"` / `"Lookup"`	`"Random"`	How the text is generated. See Modes.
`nullPercentageMax`	`number`	`0`	Upper bound (0-100) of the percentage of rows that should be null. See `nullPercentageMin`.
`nullPercentageMin`	`number`	`0`	Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to `nullPercentageMax` for an exact rate.
`postfix`	`string?`	none	Text added to the end of the value, after `caseOutput` is applied. `Random` only.
`prefix`	`string?`	none	Text added to the start of the value, after `caseOutput` is applied. `Random` only.
`seed`	`integer`	random	Per-field seed, overriding the request's own `seed` for this field only.
`unique`	`boolean`	`false`	Whether every generated value must differ from the others. See Unique values.
`wordPopularityMax`	`number?`	none	The maximum popularity (0-100) of a word. See Word popularity. `Word` only.
`wordPopularityMin`	`number?`	none	The minimum popularity (0-100) of a word. See Word popularity. `Word` only.
`wordPopularityRamp`	`number`	`0`	How strongly the selection of words is weighted toward popular words (0-100). See Word popularity. `Word` only.

Modes

Random generates random characters from the alphabet of language, with a length from minLength to maxLength.
Word generates one or more dictionary words in language, separated by spaces.
Sentence generates one or more sentences in language, separated by spaces.
Lookup selects from the values in lookupValues, optionally weighted, and writes each value exactly as listed. See LookupValue.

Properties by mode

A property that does not apply to the mode is rejected, so a request that sets one fails before any data is generated. language is the exception: it has a default, so it is ignored in Lookup mode.

Property	Random	Word	Sentence	Lookup
`minLength`, `maxLength`	Yes	Yes
`minWords`, `maxWords`		Yes
`minSentences`, `maxSentences`			Yes
`beginsWith`		Yes
`wordPopularityMin`, `wordPopularityMax`, `wordPopularityRamp`		Yes
`prefix`, `postfix`	Yes
`caseOutput`	Yes	Yes	Yes
`language`	Yes	Yes	Yes
`lookupValues`				Yes
`nullPercentageMin`, `nullPercentageMax`	Yes	Yes	Yes	Yes

minLength and maxLength have a different meaning in each mode. In Random they set the number of characters generated. In Word they limit the words that can be used, so a narrow range with beginsWith can leave few words.

A value with more than one word or sentence does not repeat a word or sentence within the value. Without wordPopularityRamp, a word or sentence is not repeated in another row either, until the rows have used every available word or sentence.

LookupValue

Lookup mode selects from a list of values. Each entry is an object with a value and an optional weight:

Property	Type	Default	Description
`value`	`string`	required	The value.
`weight`	`number`	`1`	The entry's weight relative to the other entries in the list. Must be greater than 0.

Weights are relative, not percentages, so they do not need to total any particular number. 3 and 1 give the same distribution as 30 and 10: the first entry is selected three times as often as the second. With no weights set, every entry is equally likely.

The list must contain at least one entry.

Weights that total 100 can be read as percentages:

{
  "type": "String",
  "mode": "Lookup",
  "lookupValues": [
    { "value": "Delivered", "weight": 70 },
    { "value": "In transit", "weight": 20 },
    { "value": "Returned", "weight": 7 },
    { "value": "Lost", "weight": 3 }
  ],
  "seed": 1,
  "map": { "value": { "column": "status", "dataType": "VarChar" } }
}

Sample output:

status
Delivered
Delivered
Delivered
In transit
Delivered
Delivered
Delivered
Returned

Each row is selected separately, so the proportions are approximate.

The same kind of list with no weights:

{
  "type": "String",
  "mode": "Lookup",
  "lookupValues": [
    { "value": "Small" },
    { "value": "Medium" },
    { "value": "Large" }
  ],
  "seed": 2,
  "map": { "value": { "column": "size", "dataType": "VarChar" } }
}

Sample output:

size
Large
Medium
Small
Large
Small
Small

CaseOutput

caseOutput changes the case of the generated text. It is applied last, so it does not affect which words are used or whether values are unique. Other field types with a case property use the same values.

Value	Effect
`None`	No change. The default.
`Lower`	Every letter in lower case.
`Upper`	Every letter in upper case.
`Proper`	The first letter after each space in upper case, and every other letter in lower case. `o'brien` is `O'brien`.

Languages

language sets the language of Word and Sentence mode. See GET /v1/words/languages and GET /v1/sentences/languages for the languages available.

In Random mode, language sets the alphabet: the lower-case letters of the language, including its accented letters, such as ñ for Spanish and ø for Danish. Japanese uses hiragana and katakana, and Korean uses Hangul syllables.

Word popularity

A word's popularity is its rank by frequency of use in its language, from 0 for the least common words to 100 for the most common. Words with the same frequency have different ranks, so a popularity range always selects that share of the language's words. A range from 80 to 95 is 15% of the words.

The words include names, abbreviations and specialized terms, so the most popular words are not only everyday vocabulary.

wordPopularityMin and wordPopularityMax can be set separately. Set one for an open range, both for a closed range, or neither for every word.

The most popular 10% of words, with wordPopularityMin set to 90:

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "wordPopularityMin": 90,
  "map": { "value": { "column": "word", "dataType": "VarChar" } }
}

Sample output:

word
hoodie
thinker
Turf
ISI
chooses
Capaldi
Courthouse
whiff

The least popular 10%, with wordPopularityMax set to 10:

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "wordPopularityMax": 10,
  "map": { "value": { "column": "word", "dataType": "VarChar" } }
}

Sample output:

word
Boukili
Edelberg
Comma
Apartheid-era
Cig
CMHC’s
Chisham
Davon

The middle 20%, from 40 to 60:

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "wordPopularityMin": 40,
  "wordPopularityMax": 60,
  "map": { "value": { "column": "word", "dataType": "VarChar" } }
}

Sample output:

word
service-technology
jacket’s
non-potassium
soundtrack-style
verification-focused
tinpot
pasta's
Hedgerow

Weighting toward popular words

wordPopularityRamp weights the selection toward the more popular words in the popularity range. At 0, the default, every word in the range is equally likely. Above 0, a word's weight is its popularity divided by 100, raised to the power of wordPopularityRamp × 0.08. Across the full range, the average popularity of the selected words is 50 at a ramp of 0, about 83 at 50, and 90 at 100.

With wordPopularityRamp above 0, words are selected separately for each row, so a word can appear in more than one row, and some words in the range might not appear at all.

Every word equally likely, with wordPopularityRamp at 0:

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "wordPopularityRamp": 0,
  "map": { "value": { "column": "word", "dataType": "VarChar" } }
}

Sample output:

word
Acoustic
Deok-sun
gold-mining
Tallaght
Purch
Kazakhs
Hand-waving
Anne-Shirley

The strongest weighting, with wordPopularityRamp at 100:

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "wordPopularityRamp": 100,
  "map": { "value": { "column": "word", "dataType": "VarChar" } }
}

Sample output. A single word does not show its rank, but the average popularity of these words is about 90, against about 50 in the example above:

word
Tyler
BNPL
court-approved
grim
alertly
emailed
referrals
acre

Unique values

With unique set, every row has a different value. A request for more rows than the field can produce is rejected before any data is generated, stating how many are available:

Mode	Distinct values available
`Random`	Every string of the alphabet with a length from `minLength` to `maxLength`.
`Word`	The number of ordered arrangements of `maxWords` different words from the words that match the filters.
`Sentence`	The number of ordered arrangements of `maxSentences` different sentences from the sentences in the language.
`Lookup`	The number of different values in `lookupValues`.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request, not a complete request on its own. See Building a Request for how it fits into a full DatasetRequest.

A random eight-letter code

{
  "type": "String",
  "mode": "Random",
  "minLength": 8,
  "maxLength": 8,
  "caseOutput": "Upper",
  "map": { "value": { "column": "code", "dataType": "VarChar" } }
}

Sample output:

code
QOOSUWAP
ZOOKQHPO
YXDXHAHR
CXKDJMKM
QKGRXHRY
WQBQAIFM

A product name of two to four words

Words from the most popular 20% of English words, with the first letter of each word in upper case.

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "minWords": 2,
  "maxWords": 4,
  "wordPopularityMin": 80,
  "caseOutput": "Proper",
  "seed": 3,
  "map": { "value": { "column": "product_name", "dataType": "VarChar" } }
}

Sample output:

product_name
Shuddering Braille Consular Mentorship
Bronze Tino Stark Moisturizing
Executed Power
Searched Jumper Teammates
Jhon Ethanol
Persistence Turmoil

A description of one to three sentences

{
  "type": "String",
  "mode": "Sentence",
  "language": "English",
  "minSentences": 1,
  "maxSentences": 3,
  "seed": 2,
  "map": { "value": { "column": "description", "dataType": "VarChar" } }
}

Sample output:

description
Players still match color, number and symbol but instead of every-man-for-himself, they team up in pairs of two and play together to win. He even wore it as he began to argue with Appel over their management contract, and the dispute deteriorated into a vicious legal battle by summer 1976.
Michael was a 20-year retired veteran of the United States Army and was a helicopter mechanic during most of his career.
A compact signal amplifier chip, developed by the European Space Agency, enhances space communication by boosting faint signals to usable levels. The undercard fighters at most boxing events get paid well below what the UFC fighters get paid on the preliminary card of events, no matter how big or what venue is hosting it. The Government isn't meeting its own EV targets, despite pushing motorists towards electric cars by increasing taxes and running costs of hybrid, petrol and diesel.
If you're not a fan of these effects showing up everywhere, you can tone them down by adjusting a couple of settings.

A weighted status

{
  "type": "String",
  "mode": "Lookup",
  "lookupValues": [
    { "value": "Active", "weight": 8 },
    { "value": "Pending", "weight": 1 },
    { "value": "Closed", "weight": 1 }
  ],
  "seed": 2,
  "map": { "value": { "column": "status", "dataType": "VarChar" } }
}

Sample output:

status
Active
Active
Active
Closed
Active
Active
Pending
Active

A code with a prefix and a postfix

prefix and postfix are added after caseOutput is applied, exactly as written.

{
  "type": "String",
  "mode": "Random",
  "minLength": 6,
  "maxLength": 6,
  "caseOutput": "Upper",
  "prefix": "ORD-",
  "postfix": "-UK",
  "map": { "value": { "column": "order_ref", "dataType": "VarChar" } }
}

Sample output:

order_ref
ORD-KELLRX-UK
ORD-KMFPBX-UK
ORD-TBRIWV-UK
ORD-BXIGGM-UK
ORD-UPWNEB-UK
ORD-EIEUSW-UK

Words starting with chosen letters

Popular English words of at least five letters that start with b or c.

{
  "type": "String",
  "mode": "Word",
  "language": "English",
  "beginsWith": ["b", "c"],
  "minWords": 1,
  "maxWords": 1,
  "minLength": 5,
  "wordPopularityMin": 95,
  "caseOutput": "Proper",
  "map": { "value": { "column": "code_name", "dataType": "VarChar" } }
}

Sample output:

code_name
Blocks
Bilbao
Brake
Bucket
Chase
Children's
Celebrations
Bullpen

A code in another alphabet

In Random mode, language sets the alphabet.

{
  "type": "String",
  "mode": "Random",
  "language": "Greek",
  "minLength": 5,
  "maxLength": 8,
  "map": { "value": { "column": "greek_code", "dataType": "VarChar" } }
}

Sample output:

greek_code
οδκημθπρ
εαβξφβλρ
τηβιθζ
ρακζηνι
ζτοαλκβμ
πμκπαθμ

A unique lower-case token

{
  "type": "String",
  "mode": "Random",
  "minLength": 10,
  "maxLength": 10,
  "caseOutput": "Lower",
  "unique": true,
  "map": { "value": { "column": "token", "dataType": "VarChar" } }
}

Sample output:

token
nmhtsowrtc
cqybwquyzj
vizcybkalf
aszdraytak
jzcktcfucn
mryuqpuhsq

Null rows

{
  "type": "String",
  "mode": "Lookup",
  "lookupValues": [{ "value": "Gold" }, { "value": "Silver" }, { "value": "Bronze" }],
  "nullPercentageMin": 40,
  "nullPercentageMax": 40,
  "seed": 13,
  "map": { "value": { "column": "loyalty_tier", "dataType": "VarChar" } }
}

Sample output:

loyalty_tier
Silver
Gold

Bronze
Silver

Table of Contents

String

Properties

Modes

Properties by mode

LookupValue

CaseOutput

Languages

Word popularity

Weighting toward popular words

Unique values

Examples

A random eight-letter code

A product name of two to four words

A description of one to three sentences

A weighted status

A code with a prefix and a postfix

Words starting with chosen letters

A code in another alphabet

A unique lower-case token

Null rows