> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> We're glad to see you here. Today we're going to install SDF and create a hello world project. Let's get started.

## Creating a Workspace

To create a new SDF Workspace, run the following command:

```shell theme={null}
sdf new --sample hello && cd hello
```

After running the command, you will see the following output:

<div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
  <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-shell">
    <code className="language-shell">
          Created hello/.gitignore
          Created hello/models/main.sql
          Created hello/workspace.sdf.yml
       
              Welcome to your new SDF Workspace! To help you on your journey:
              
              💡 Join the SDF Community Slack -> [https://sdf.com/join](https://sdf.com/join) 
              
              📚 Read the Docs to Get Started -> [https://docs.sdf.com/](https://docs.sdf.com/)
              
         Finished new in 0.289 secs
    </code>
  </pre>
</div>

<Tip>
  You can view and modify the source code for all our examples directly in our [GitHub repository](https://github.com/sdf-labs/sdf-cli/tree/main/examples).
</Tip>

This will create a new directory with the name of your workspace. In this case, that's `hello`. The workspace will contain the following files and folder structure:

<div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
  <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-shell">
    <code className="language-shell">
      .
      ├── models
      │   └── main.sql
      └── workspace.sdf.yml

      2 directories, 2 files
    </code>
  </pre>
</div>

The directory will contain a `workspace.sdf.yml` file, which is the primary configuration file for your project. It contains the following YML:

<div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
  <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-yml">
    <code className="language-yml">
      workspace:
        name: hello
        edition: "1.3"
        description: "A minimal workspace"

        includes:
          - path: models
    </code>
  </pre>
</div>

For more on this, see our [workspaces guide](/guide/setup/workspaces) and for a full reference to our YML schema and more see the [reference section](/reference/sdf-yml).

Lastly, our workspace contains a single model file, `main.sql`, which contains the following SQL:

<div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
  <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-sql">
    <code className="language-sql">
      select 'Hello World!' as message
    </code>
  </pre>
</div>

Next, let's take a deeper look at your project.

<Note>
  SDF uses a cache to fingerprint outputs and accelerate recomputation. This cache is by default located in the `sdftarget/` directory.
  The cache is machine specific and should not be checked in to git. An appropriate `.gitignore` file is created as part of the `sdf new` command.
</Note>

<Info>
  We refer to SQL statements in SDF as `models`. Models are SQL statements that will materialized in your data warehouse, or locally with the SDF DB. They differ from tables
  as they can be materialized as tables, views, and more based on the configuration. Furthermore, they can be templatized with jinja and SDF SQL variables. SDF recommends specifying one model per file, as each model receives a fully qualified name (`database.schema.table`) that can correspond nicely to a directory structure.
  See our [indexing documentation](/guide/advanced/index) for more.
</Info>

## Exploring Your Project

Let's see just how easy it is to set up SDF and run your first query.

<Steps>
  <Step title="Static Analysis with `sdf compile`">
    First, we'll run the core command of SDF: [sdf compile](/reference/sdf-cli#sdf-compile).

    The `--show` flag allows you to modulate SDF's output and the `all` option indicates that we would like to see all schemas from all models referenced in the workspace.

    ```shell theme={null}
    sdf compile --show all
    ```

    Your output should look like:

    <div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
      <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-shell">
        <code className="language-shell">
          Working set 1 model file, 1 .sdf file
            Compiling hello.pub.main (./models/main.sql)
             Finished 1 model \[1 succeeded] in 0.871 secs

          Schema hello.pub.main
          ┌─────────────┬──────────────────┬────────────┬─────────────┐
          │ column\_name ┆ data\_type        ┆ classifier ┆ description │
          ╞═════════════╪══════════════════╪════════════╪═════════════╡
          │ message     ┆ varchar not null ┆            ┆             │
          └─────────────┴──────────────────┴────────────┴─────────────┘
        </code>
      </pre>
    </div>

    As you can see from the output, SDF has statically analyzed the query and determined there's a single non-nullable column named `column` and it's of type `varchar`.
    You'll also see an empty `classifier` block in the output. This is for metadata we'll attach to columns, but we'll get to that later.
  </Step>

  <Step title="Create a New Model">
    Now, create a new file in the source directory called `main2.sql` with the query:

    ```sql main2.sql theme={null}
    SELECT * FROM main;
    ```
  </Step>

  <Step title="Lineage with `sdf lineage`">
    SDF guarantees rich column level lineage. The command below specifies a particular column, in a particular table that we would like to inspect.

    ```shell theme={null}
    sdf lineage main2 --column message
    ```

    <div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
      <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-shell">
        <code className="language-shell">
          Working set 2 model files, 1 .sdf file
            Compiling hello.pub.main (./models/main.sql)
            Compiling hello.pub.main2 (./models/main2.sql)
             Finished 2 models \[2 succeeded] in 0.853 secs
          hello.pub.main2.message
          │
          │ copy
          └──────┐
                 hello.pub.main.message
        </code>
      </pre>
    </div>
  </Step>

  <Step title="Execution with `sdf run`">
    Next, let's execute the query, using SDF as the database. We'll execute the query with SDF's integrated execution runtime, right on your machine.

    ```shell theme={null}
    sdf run --show all
    ```

    Your output should look like:

    <div className="bg-[#0F1117] dark:bg-codeblock rounded-xl dark:ring-1 dark:ring-gray-800/50 relative">
      <pre style={{ fontFamily: 'monospace', backgroundColor: 'transparent' }} className="language-shell">
        <code className="language-shell">
          Working set 2 model files, 1 .sdf file
              Running hello.pub.main (./models/main.sql)
              Running hello.pub.main2 (./models/main2.sql)
             Finished 2 models \[2 succeeded] in 0.854 secs

          Table hello.pub.main
          ┌──────────────┐
          │ message      │
          ╞══════════════╡
          │ Hello World! │
          └──────────────┘
          1 rows.

          Table hello.pub.main2
          ┌──────────────┐
          │ message      │
          ╞══════════════╡
          │ Hello World! │
          └──────────────┘
          1 rows.
        </code>
      </pre>
    </div>
  </Step>
</Steps>

In this guide we showed you just how easy it is to install SDF and run your first query.

<Tip>
  If using VSCode, SDF's YML schema is available for type and syntax checking via the [Red HAT YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). This will
  add auto-fill, type checking, and YML validation directly inline while editing `sdf.yml` files.
</Tip>

## Quick Links

<CardGroup cols={2}>
  <Card title="Tutorials" href="/tutorials/tutorials-intro">
    Try it yourself! Get to know the real value of SDF through our short series of tutorials
  </Card>

  <Card title="Setup SDF" href="/guide/setup/io">
    Learn more about setting up SDF in your data stack
  </Card>
</CardGroup>