Skip to main content

string_field()

Create a string column specification for use in a schema.

Usage

Source

string_field(
    min_length=None,
    max_length=None,
    pattern=None,
    preset=None,
    allowed=None,
    nullable=False,
    null_probability=0.0,
    unique=False,
    generator=None,
)

The string_field() function defines the constraints and behavior for a string column when generating synthetic data with generate_dataset(). It provides three main modes of string generation: (1) controlled random strings with min_length=/max_length=, (2) strings matching a regular expression via pattern=, or (3) realistic data using preset= (e.g., "email", "name", "address"). You can also restrict values to a fixed set with allowed=. Only one of preset=, pattern=, or allowed= can be specified at a time.

When no special mode is selected, random alphanumeric strings are generated with lengths between min_length= and max_length= (defaulting to 1–20 characters).

Parameters

min_length: int | None = None

Minimum string length (for random string generation). Default is None (defaults to 1). Only applies when preset=, pattern=, and allowed= are all None.

max_length: int | None = None

Maximum string length (for random string generation). Default is None (defaults to 20). Only applies when preset=, pattern=, and allowed= are all None.

pattern: str | None = None

Regular expression pattern that generated strings must match. Supports character classes (e.g., [A-Z], [0-9]), quantifiers (e.g., {3}, {2,5}), alternation, and groups. Cannot be combined with preset= or allowed=.

preset: str | None = None

Preset name for generating realistic data. When specified, values are produced using locale-aware data generation, and the country= parameter of generate_dataset() controls the locale. Cannot be combined with pattern= or allowed=. See the Available Presets section below for the full list.

allowed: list[str] | None = None

List of allowed string values (categorical constraint). Values are sampled uniformly from this list. Cannot be combined with preset= or pattern=.

nullable: bool = False

Whether the column can contain null values. Default is False.

null_probability: float = 0.0

Probability of generating a null value for each row when nullable=True. Must be between 0.0 and 1.0. Default is 0.0.

unique: bool = False

Whether all values must be unique. Default is False. When True, the generator will retry until it produces n distinct values.

generator: Callable[[], Any] | None = None
Custom callable that generates values. When provided, it’s used instead of the other constraints, while unique= and nullable= still apply. The callable should take no arguments and return a single string value. It isn’t controlled by the seed= of generate_dataset(), so it needs its own seeded random number generator for reproducible data.

Returns

StringField
A string field specification that can be passed to Schema().

Raises

ValueError
If more than one of preset=, pattern=, or allowed= is specified; if allowed= is an empty list; if min_length or max_length is negative; if min_length exceeds max_length; or if preset is not a recognized preset name.

Available Presets

The preset= parameter accepts one of the following preset names, organized by category. When a preset is used, the country= parameter of generate_dataset() controls the locale for region-specific formatting (e.g., address formats, phone number patterns).

Personal: "name" (first + last name), "name_full" (full name with possible prefix or suffix), "first_name", "last_name", "gender" (person’s gender, coherent with name), "email" (realistic email address), "phone_number", "address" (full street address), "city", "state", "country", "country_code_2" (ISO 3166-1 alpha-2 code, e.g., "US"), "country_code_3" (ISO 3166-1 alpha-3 code, e.g., "USA"), "postcode", "latitude", "longitude"

Business: "company" (company name), "job" (job title), "catch_phrase"

Internet: "url", "domain_name", "ipv4", "ipv6", "user_name", "password"

Text: "text" (paragraph of text), "sentence", "paragraph", "word"

Financial: "credit_card_number", "credit_card_provider" (Visa, Mastercard, American Express, or Discover), "iban", "currency_code"

Identifiers: "uuid4", "md5" (MD5 hash, 32 hex chars), "sha1" (SHA-1 hash, 40 hex chars), "sha256" (SHA-256 hash, 64 hex chars), "ssn" (social security number), "license_plate"

Barcodes: "ean8" (EAN-8 barcode with valid check digit), "ean13" (EAN-13 barcode with valid check digit)

Date/Time (as strings): "date_this_year", "date_this_decade", "date_between" (random date between 2000–2025), "date_range" (two dates joined with an en-dash, e.g., "2012-05-12 – 2015-11-22"), "future_date" (up to 1 year ahead), "past_date" (up to 10 years back), "time"

Miscellaneous: "color_name", "file_name", "file_extension", "mime_type", "user_agent" (browser user agent string with country-specific browser weighting), "locale_code" (locale identifier like "en_US", "de_DE"; multilingual countries return a random official locale)

Coherent Data Generation

When multiple columns in the same schema use related presets, the generated data will be coherent across those columns within each row. Specifically:

  • Person-related presets ("name", "name_full", "first_name", "last_name", "gender", "email", "user_name"): the email and username will be derived from the person’s name, and "gender" will match the person’s first name.
  • Address-related presets ("address", "city", "state", "postcode", "phone_number", "latitude", "longitude"): the city, state, and postcode will correspond to the same location within the address.
  • Credit card presets ("credit_card_number", "credit_card_provider"): the card number prefix and provider name will be consistent (e.g., “Visa” with a “4”-prefixed number).

This coherence is automatic and requires no additional configuration.

Examples

The preset= parameter generates realistic personal data, while allowed= restricts values to a categorical set:

import pointblank as pb

schema = pb.Schema(
    name=pb.string_field(preset="name"),
    email=pb.string_field(preset="email", unique=True),
    status=pb.string_field(allowed=["active", "pending", "inactive"]),
)

pb.preview(pb.generate_dataset(schema, n=100, seed=23))
PolarsRows100Columns3
name
String
email
String
status
String
1 Doris Martin d_martin@aol.com pending
2 Nancy Gonzalez nancygonzalez@icloud.com pending
3 Jessica Turner jturner@aol.com inactive
4 George Evans georgeevans@zoho.com pending
5 Patricia Williams pwilliams@outlook.com active
96 Isaiah Murphy isaiah.murphy@zoho.com active
97 Brittany Rodriguez brodriguez@yandex.com active
98 Megan Stevens mstevens26@aol.com active
99 Pamela Jenkins pjenkins29@yandex.com inactive
100 Stephanie Santos stephanie.santos40@gmail.com active

We can also generate strings that match a regular expression with pattern= (e.g., product codes, identifiers):

schema = pb.Schema(
    product_code=pb.string_field(pattern=r"[A-Z]{3}-[0-9]{4}"),
    batch_id=pb.string_field(pattern=r"BATCH-[A-Z][0-9]{3}"),
    sku=pb.string_field(pattern=r"[A-Z]{2}[0-9]{6}"),
)

pb.preview(pb.generate_dataset(schema, n=30, seed=23))
PolarsRows30Columns3
product_code
String
batch_id
String
sku
String
1 TUA-7878 BATCH-C572 ON747986
2 CIR-3746 BATCH-E915 RG842341
3 JKS-6678 BATCH-Y948 MT768044
4 DVC-7585 BATCH-E014 KN345811
5 BLC-1897 BATCH-X610 IO470502
26 GFC-4249 BATCH-K937 BZ789672
27 BKQ-1618 BATCH-E186 VL008570
28 ZAI-6997 BATCH-M421 DQ431897
29 AXI-9531 BATCH-R168 IA831952
30 LOT-0185 BATCH-U105 BZ850635

For random alphanumeric strings, min_length= and max_length= control the length. Adding nullable=True introduces missing values:

schema = pb.Schema(
    short_code=pb.string_field(min_length=3, max_length=5),
    notes=pb.string_field(
        min_length=10, max_length=50,
        nullable=True, null_probability=0.4,
    ),
)

pb.preview(pb.generate_dataset(schema, n=30, seed=7))
PolarsRows30Columns2
short_code
String
notes
String
1 tU42 None
2 MEcNn 4zs23WtLuh9sGp7VDs12SAQlXK8Ey41VEhvtMJqGrHjB8
3 jnO5 None
4 4iq tzSuQ08PkX1mAzXNMgFeMm
5 4Ev CHCDN7OCn1VA0UGobtiFtBMHvFsvgh4tPLf2HYZy76OE0Fx4VG
26 tRt None
27 8gGNT None
28 Nsz None
29 AfwD3 oPnSPvRPVOvRbABS9rwsnTbmQJ4xY4UhXKSkUO6Fk
30 zbInW kKWu7q4gmGMzIc

It’s possible to combine business and internet presets to build a company directory:

schema = pb.Schema(
    company=pb.string_field(preset="company"),
    domain=pb.string_field(preset="domain_name"),
    industry_tag=pb.string_field(allowed=["tech", "finance", "health", "retail"]),
)

pb.preview(pb.generate_dataset(schema, n=20, seed=55))
PolarsRows20Columns3
company
String
domain
String
industry_tag
String
1 King Corp made.me retail
2 Robertson LLC company.gov tech
3 Premier Analytics hand.com health
4 Superior Research who.tech finance
5 Slack had.com tech
16 Microsoft been.biz health
17 Coleman Realty number.app tech
18 Gonzalez and Riley the.app finance
19 Prestige Technologies Partners day.dev tech
20 Rodriguez Ltd back.site retail

Unlike the person and address presets, "domain_name" isn’t coherent with "company", so each domain is unrelated to the company in its row. The industry_tag values come from the allowed= list, also independently of the company.